Geteilte Partials

Ein Partial ist ein Stück Vorlage, das eine andere Vorlage über seinen Namen einbindet: ein Briefkopf, ein Adressblock, ein Absatz mit Geschäftsbedingungen. Formfeed kennt zwei Arten.

	Partials der Vorlage	Geteilte Partials
Gehört zu	Einer Version einer Vorlage	Der Organisation, nutzbar aus jedem Workspace
Angelegt über	Den Ordner partials/ eines Projekts und formfeed templates push (Partials)	Die Seite Partials in der App, formfeed partials push oder PUT /partials/{name}
Wann es sich ändert	Mit der nächsten Version, die Sie pushen	Live, ab dem nächsten Rendering jeder Vorlage, die es einbindet
Gut für	Struktur innerhalb einer Vorlage	Was jedes Dokument der Organisation gleich zeigen muss

Beide Arten binden Sie mit der Syntax der Vorlagensprache ein:

Jinja2	Liquid	Handlebars
{% include "letterhead" %}	{% include "letterhead" %}	{{> letterhead}}

Geteilte Partials sehen dieselben Daten wie die Vorlage, auch brand, und dürfen weitere geteilte Partials einbinden (bis zu 8 Ebenen tief). Verwenden Sie in Liquid include: Ein Partial, das mit {% render "letterhead" %} eingebunden wird, sieht nur brand und die Werte, die Sie ihm übergeben ({% render "letterhead", customer: customer %}).

Formfeed findet die geteilten Partials, die eine Vorlage braucht, indem es die eingebundenen Namen liest. Schreiben Sie den Namen deshalb wörtlich:

• Jinja2: include, import, from und extends mit einem Namen in Anführungszeichen (auch {% extends "base-letter" %} funktioniert).
• Liquid: include und render mit einem Namen in Anführungszeichen.
• Handlebars: {{> letterhead}} und der Partial-Block {{#> letterhead}}…{{/letterhead}}, mit dem Namen ohne Anführungszeichen.

Ein Name, der aus einer Variable kommt ({% include partial_name %}), oder in Handlebars ein Name in Anführungszeichen ({{> "letterhead"}}) erreicht nie ein geteiltes Partial: Das Rendering schlägt mit einem Vorlagenfehler fehl, als gäbe es das Partial nicht.

In der App anlegen

Öffnen Sie Partials in der Navigation der Organisation und wählen Sie Neues Partial. Ein Partial hat:

• einen Namen: Kleinbuchstaben, Ziffern, Bindestriche und Unterstriche, beginnend und endend mit einem Buchstaben oder einer Ziffer, höchstens 64 Zeichen, eindeutig in der Organisation;
• eine Engine: Jinja2, Liquid oder Handlebars. Ein geteiltes Partial wird nur von Vorlagen derselben Engine gefunden;
• optional eine Beschreibung (bis zu 300 Zeichen) und den Quelltext (bis zu 256 KB), bearbeitet im selben Code-Editor wie Vorlagen.

Jede Zeile zeigt die Include-Zeile des Partials; ein Klick darauf legt sie in die Zwischenablage (der Bearbeiten-Dialog hat denselben Button). Außerdem zeigt die Tabelle Version, Engine, in welchen Vorlagen das Partial verwendet wird (Spalte Verwendet in, mit der Zahl der veröffentlichten) und wann es zuletzt aktualisiert wurde. Eine Vorlage verwendet ein Partial, wenn ihre veröffentlichte Version oder ihr neuester Entwurf den Namen einbindet und kein Partial der Vorlage mit demselben Namen hat; geteilte Partials, die es einbinden, stehen ebenfalls dort. Der Engine-Filter zeigt, was Vorlagen einer Sprache einbinden können; die Suche findet Partials nach Namen.

Inhaber, Admins und Editoren legen geteilte Partials in der App an, bearbeiten, benennen um (Bearbeiten oder umbenennen im Menü einer Zeile) und löschen sie; Betrachter sehen sie. Über die API darf jeder Schlüssel mit template:write sie schreiben. Eine Organisation hat bis zu 200, in jedem Plan.

Änderungen gelten sofort

Speichern Sie eine Änderung an einem Partial, das Vorlagen verwenden, listet der Dialog zuerst diese Vorlagen auf, markiert als Veröffentlicht oder Entwurf, und fragt nach einer Bestätigung: Das nächste Rendering jeder dieser Vorlagen verwendet die neue Version, auch bei veröffentlichten, ohne neue Version der Vorlage.

• Wer ein verwendetes Partial umbenennt, bricht die Includes mit dem alten Namen; diese Vorlagen schlagen beim Rendern fehl, bis das Include angepasst ist.
• Beim Löschen eines verwendeten Partials nennt die App die Vorlagen, die danach fehlschlagen, und verlangt zur Bestätigung den Namen des Partials.
• API-Renderings lesen geteilte Partials über einen Cache von bis zu 60 Sekunden; eine Änderung in der App erreicht sie also innerhalb einer Minute. Eine Änderung über die API oder die CLI leert diesen Cache und gilt deshalb meist sofort.
• Die Version eines Partials steigt, wenn sich sein Quelltext oder seine Engine ändert; ein neuer Name oder eine neue Beschreibung behält die Version. Jedes Rendering hält die Versionen der geteilten Partials, die es verwendet hat, als shared_partials ({ "letterhead": 4 }) in seinem Nachweis zur Reproduzierbarkeit fest, den die Details des Renderings auf der Seite Renderings der App unter Reproduzierbarkeit zeigen (das Render-Objekt der API enthält ihn nicht), und ein Rendering wird nur dedupliziert, wenn diese Versionen unverändert sind.

Wie ein Name aufgelöst wird

Für jedes Include sucht Formfeed in dieser Reihenfolge:

1. in den Partials der Vorlage, die mit der Version gespeichert sind, mit exaktem Namen;
2. in den geteilten Partials der Engine der Vorlage, ohne Beachtung von Groß- und Kleinschreibung und mit einer ignorierten Dateiendung (.html, .htm, .j2, .njk, .jinja, .liquid, .hbs, .handlebars). {% include "Letterhead.html" %} findet also das geteilte Partial letterhead.

Ein Partial der Vorlage mit demselben Namen verdeckt das geteilte. Das ist nützlich für eine gewollte Ausnahme und eine Falle, wenn es eine alte Kopie ist: Der Editor zeigt dann in der Liste Probleme den Hinweis Das mit dieser Vorlage gespeicherte Partial „letterhead“ verdeckt das geteilte Partial „letterhead“. Um das geteilte zu verwenden, führen Sie im Projekt formfeed partials pull letterhead aus (das den Namen als geteilt vermerkt) und pushen die Vorlage erneut: Die neue Version trägt keine eigene Kopie mehr.

Mit einem Rendering reisen nur die geteilten Partials, die eine Vorlage tatsächlich einbindet (direkt oder über andere Partials, im Inhalt, in der Kopf- oder Fußzeile); zusammen dürfen sie bis zu 2 MB groß sein, darüber antwortet das Rendering mit 400 invalid_request und nennt die Partials. Word- und PowerPoint-Vorlagen bekommen das Brand Kit, aber keine geteilten Partials. Lassen sich die Partials nicht lesen, schlägt die Anfrage mit 500 worker_exhausted fehl, bevor ein Rendering angelegt ist, und kostet nichts (siehe Wie Renderings sie verwenden).

Mit geteilten Partials im Projekt arbeiten

Geteilte Partials liegen im selben Ordner partials/ wie die Partials der Vorlagen, als <name>.html. Die CLI unterscheidet sie über .formfeed/state.json, wo formfeed partials pull und push jedes geteilte Partial mit Engine und Remote-Version vermerken.

npx formfeed partials list               # Name, Engine, Version, lokaler Stand (behind, modified)
npx formfeed partials pull               # alle geteilten Partials, oder einzelne: pull letterhead
# partials/letterhead.html bearbeiten, Vorschau mit formfeed dev
npx formfeed partials push letterhead    # legt Version 4 an

• Neue Partials: formfeed partials push <name> legt das Partial aus partials/<name>.html an. Die Engine ist die des Projekts, außer Sie übergeben --engine jinja2|liquid|handlebars. Ohne Namen sendet push jedes vermerkte geteilte Partial, das sich geändert hat; --dry-run zeigt, was gesendet würde.
• Konflikte: push sendet die zuletzt gepullte Version als base_version. Hat jemand das Partial seitdem geändert, bricht der Push mit Exit-Code 2 ab (… changed remotely since v3; run formfeed partials pull letterhead and merge, or push with --force). Pullen Sie, führen Sie Ihre Änderung zusammen und pushen Sie erneut, oder überschreiben Sie mit --force. Einen Namen zu pushen, der remote schon existiert, aber nie gepullt wurde, verweigert die CLI ebenso.
• Vorlagen pushen: formfeed templates push lässt als geteilt vermerkte Partials aus der Version heraus, weil sie live aufgelöst werden, und meldet sie nicht als fehlend. Ein Include, das weder eine Datei noch ein vermerktes geteiltes Partial hat, stoppt den Push weiterhin.
• Lokal rendern: formfeed dev, render, test und validate lösen Includes aus dem Ordner partials/ auf. Pullen Sie also zuerst, um mit den aktuellen geteilten Partials zu arbeiten.

Betrifft eine Änderung beides, führen Sie in der CI formfeed partials push vor formfeed templates push --publish aus. So rendert keine Vorlage gegen ein Partial, das es noch nicht gibt.

Aus Code

Die API für Brand Kit und Partials listet, liest, schreibt und löscht geteilte Partials mit template:read und template:write; die SDKs für TypeScript und Python bieten dafür partials.list(), get, put und delete. Ein Partial wird über seinen Namen angesprochen, den die API in Kleinbuchstaben speichert:

curl -X PUT https://api-eu.formfeed.dev/v1/partials/letterhead \
  -H "Authorization: Bearer $FORMFEED_API_KEY" -H "Content-Type: application/json" \
  -d '{ "engine": "jinja2", "source": "<header>{{ brand.name }}</header>", "base_version": 3 }'

engine und source sind Pflicht, description ist optional, und base_version macht das Schreiben bedingt: Hat sich das Partial seit dieser Version geändert, antwortet die API mit 409 conflict und schreibt nichts (siehe Konflikte). Umbenennen geht nur in der App.