Variable-Entwicklerdokumentation

Variablen sind wiederverwendbare, templatesgesteuerte Fragmente, die innerhalb von FaceFlow-verwalteten Kontexten gerendert werden.

Für technische Anwender sind Variablen eines der leichtgewichtigsten Wiederverwendungsprimitiven in FaceFlow. Sie eignen sich, wenn Ausgabe über Layouts, Komponenten, Listen oder andere Renderflächen hinweg geteilt werden soll, ohne ein vollständiges Component-Schema einzuführen.

Kernaufgabe

Eine Variable ist verantwortlich für:

wiederverwendbare Template-Ausgabe
optionales CSS und clientseitiges Verhalten
einfache Parametrisierung über Attribute
kontextbewusstes Rendering
cache-bewusste Auslieferung für wiederholte Ausgaben

Verwenden Sie eine Variable, wenn die Wiederverwendungseinheit kleiner als eine Komponente, aber dauerhafter als kopierter Markup-Code ist.

Variable-Modell

Eine typische Variable beinhaltet:

eine stabile Identität
ein Facet-Template
optionales CSS
optionales JavaScript
optionale Attribute
Kategorie- und Beschreibungsmatadaten
einen Cache-Modus

Konzeptionell:

{
  "name": "copyright-notice",
  "title": "Copyright Notice",
  "category": "footer",
  "cacheMode": "auto",
  "attributes": [
    { "name": "company", "default": "PageFace" }
  ],
  "html": "<p>&copy; {{ now.year }} {{ attr.company }}</p>",
  "css": ".copyright { color: #64748b; }",
  "js": ""
}

Die genaue Speicherimplementierung ist intern. Der obige Vertrag ist für technische Autoren der wichtige Teil.

Einbettungssyntax

Variablen werden mit der Doppelklammer-Syntax eingebettet:

[[copyright-notice]]

Mit Attributen:

[[copyright-notice company="Acme Inc"]]

Variablen können auch innerhalb anderer Templates eingebettet werden:

<footer class="site-footer">
  [[copyright-notice company="Acme Inc"]]
</footer>

Attributwerte sollten in der Einbettungssyntax als zitierte Literale übergeben werden.

Wenn eine Variable seiten- oder zur Laufzeit kontextbewusstes Verhalten benötigt, lesen Sie den Rendering-Kontext innerhalb des Variable-Templates anstatt zu versuchen, einen unzitierten Ausdruck in die Attributliste einzufügen.

Attributmodell

Attribute sind benannte Eingaben, die der Variable zur Renderzeit übergeben werden.

Sie eignen sich für:

Varianten von Text
Labels
einfache visuelle Optionen
kleine geschäftsspezifische Werte

Beispiel:

[[cta-badge label="New" tone="accent"]]

Template-Verwendung:

<span class="badge badge-{{ attr.tone | default('neutral') }}">
  {{ attr.label }}
</span>

Attribute sollten leichtgewichtig bleiben. Wenn die Wiederverwendungseinheit ein großes editierbares Schema benötigt, deutet das normalerweise auf eine Component hin.

Beispiel für sicheres Mischen von Literal-Attributen mit Laufzeitkontext:

<span class="badge badge-{{ attr.tone | default('neutral') }}">
  {{ attr.label | default(page.title) }}
</span>

Rendering-Kontext

Variablen können gegen einen breiteren Laufzeitkontext rendern. Häufige Kontextobjekte sind:

page
user
pages
site
languages / lang
now
attr

Beispiel:

<p class="eyebrow">
  {{ page.title }} updated {{ now.year }}
</p>

Oder ein abfragegesteuertes Beispiel:

<ul class="recent-posts">
  {{#pages selector="template=blog-post, sort=-published, limit=3" as="item"}}
    <li><a href="{{ item.url }}">{{ item.title }}</a></li>
  {{/pages}}
</ul>

Das macht Variablen nützlich für kleine dynamische Fragmente, ohne eine vollständige List oder Component zu benötigen.

Unterstützte Platzierung

Variablen werden häufig verwendet in:

Layout-Templates
Component-Templates
List-Templates
anderen Variablen
unterstützten Inhaltsflächen, die FaceFlow-Rendering durchreichen

Typische Beispiele:

[[site-announcement]]
[[page-breadcrumbs]]
[[recent-posts title="From the blog"]]

Verschachtelung

Variablen können andere Variablen referenzieren:

<div class="footer-meta">
  [[social-links]]
  [[copyright-notice company="PageFace"]]
</div>

Verschachtelung ist nützlich, wenn sie die Klarheit verbessert. Vermeiden Sie tiefe Ketten, die Debugging oder Einschätzungen von Änderungsfolgen erschweren.

Cache-Modi

Variablen unterstützen mehrere Cache-Strategien.

Auto

Für die meisten Fälle verwenden. Die Laufzeit bestimmt, ob statisches oder dynamisches Verhalten basierend auf den Rendering-Anforderungen angemessen ist.

Static

Verwenden, wenn die Ausgabe nicht von sich änderndem Benutzer-, Zeit- oder anfragerelevantem Kontext abhängt.

Dynamic

Verwenden, wenn die Ausgabe von häufig änderndem Kontext abhängt und sich nicht wie ein vollständig cache-freundliches Fragment verhalten soll.

Beispiel-Entscheidungsregel:

current year footer -> auto
simple shared legal text -> static
logged-in user greeting -> dynamic

Performance-Hinweise

Variablen werden oft weitreichend wiederverwendet, daher ist Performance-Disziplin wichtig.

Bevorzugen Sie auto oder static, es sei denn, es gibt einen echten Grund für dynamic
vermeiden Sie teure, abfrageintensive Ausgaben in Fragmenten, die auf vielen Seiten verwendet werden
behandeln Sie weit geteilte Variablen als performance-sensitive Assets
prüfen Sie die Auswirkungen von Änderungen, bevor Sie eine stark wiederverwendete Variable bearbeiten

Vorschau und Tests

Beim Testen einer Variable überprüfen Sie:

Rendering mit realistischen Attributen
Verhalten innerhalb des tatsächlichen Seiten- oder Komponenten-Kontexts
Ausgabe unter dem vorgesehenen Cache-Modus
Verhalten verschachtelter Variablen, falls Komposition beteiligt ist

Beispiel-Testpattern:

[[cta-badge label="Launch Ready" tone="success"]]
[[cta-badge label="New" tone="accent"]]

Wann man eine Variable verwendet

Verwenden Sie eine Variable, wenn:

das Fragment an mehreren Stellen wiederverwendet wird
die Struktur klein und stabil ist
die Eingaben begrenzt sind
die Ausgabe Kontextbewusstsein benötigt

Verwenden Sie keine Variable, wenn:

der Inhalt einzigartig für eine Seite ist
ein vollständiges editierbares Schema erforderlich ist
die Struktur groß genug ist, um ein wiederverwendbarer Abschnitt zu sein
die Ausgabe eher ein dynamisches Archiv als ein Fragment ist

Anti-Patterns

Vermeiden Sie:

Variablen in Mini-Seiten zu verwandeln
große Geschäftsabläufe in einer einzigen Variable zu verstecken
zu viele Attribute hinzuzufügen, um ein Component-Schema zu simulieren
tief verschachtelte Variable-Ketten mit unklarer Zuständigkeit
den Cache-Modus dynamic standardmäßig ohne echten Bedarf zu verwenden

Beispiel-Build-Pattern

Kleines Utility-Fragment:

[[copyright-notice company="PageFace"]]

Seitenbewusstes wiederverwendbares Snippet:

<aside class="page-summary">
  <h3>{{ page.title }}</h3>
  <p>{{ page.summary }}</p>
</aside>

Abfragegesteuertes Widget:

<div class="resource-count">
  {{ pages.count selector="template=resource-item" }} resources
</div>

FaceFlow Variables — Reusable Template Fragments