Ontwikkelaarsdocumentatie: Variabelen

Variabelen zijn herbruikbare, door templates aangedreven fragmenten die worden gerenderd binnen door FaceFlow beheerde contexten.

Voor technische gebruikers zijn Variabelen een van de lichtste herbruikbaarheidprimitieven in FaceFlow. Ze zijn geschikt wanneer uitvoer gedeeld moet worden over layouts, componenten, lijsten of andere renderoppervlakken zonder een volledig Component-schema in te voeren.

Kernverantwoordelijkheid

Een Variabele is verantwoordelijk voor:

herbruikbare template-uitvoer
optionele CSS en client-side gedrag
eenvoudige parameterisatie via attributen
contextbewuste rendering
cachebewuste levering voor herhaalde uitvoer

Gebruik een Variabele wanneer de herbruikbare eenheid kleiner is dan een Component maar duurzamer dan gekopieerde markup.

Model van een Variabele

Een typische Variabele bevat:

een stabiele identiteit
een Facet-template
optionele CSS
optionele JavaScript
optionele attributen
categorie- en beschrijvingsmetadata
een cachemodus

Conceptueel:

{
  "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": ""
}

De exacte opslagimplementatie is intern. Het bovenstaande contract is het belangrijke deel voor technische auteurs.

Insluitingssyntaxis

Variabelen worden ingesloten met de dubbelhaken-syntaxis:

[[copyright-notice]]

Met attributen:

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

Variabelen kunnen ook worden ingesloten binnen andere templates:

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

Attribuutwaarden moeten als gequote literalen worden doorgegeven in de insluitingssyntaxis.

Als een Variabele pagina-bewust of runtime-bewust gedrag nodig heeft, lees dan uit de renderingcontext binnen de Variabele-template in plaats van te proberen een ongeciteerde expressie in de attributenlijst te injecteren.

Attribuutmodel

Attributen zijn benoemde inputs die aan de Variabele worden doorgegeven tijdens het renderen.

Ze zijn geschikt voor:

copyvarianten
labels
eenvoudige visuele opties
kleine bedrijfsspecifieke waarden

Voorbeeld:

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

Templategebruik:

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

Attributen moeten lichtgewicht blijven. Als de herbruikbare eenheid een groot bewerkbaar schema nodig heeft, duidt dat meestal op een Component.

Voorbeeld van het veilig mengen van letterlijke attributen met runtime-context:

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

Rendercontext

Variabelen kunnen renderen tegen een bredere runtime-context. Gangbare contextobjecten zijn onder andere:

page
user
pages
site
languages / lang
now
attr

Voorbeeld:

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

Of een query-gedreven voorbeeld:

<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>

Dit maakt Variabelen nuttig voor kleine dynamische fragmenten zonder een volledige Lijst of Component te hoeven gebruiken.

Ondersteunde Plaatsing

Variabelen worden vaak gebruikt in:

Layout-templates
Component-templates
Lijst-templates
andere Variabelen
ondersteunde contentoppervlakken die FaceFlow-rendering doorgeven

Typische voorbeelden:

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

Nesten

Variabelen kunnen verwijzen naar andere Variabelen:

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

Nesten is nuttig wanneer het de duidelijkheid verbetert. Vermijd diepe ketens die het debuggen of het inschatten van wijzigingsimpact moeilijk maken.

Cache-modi

Variabelen ondersteunen meerdere cache-strategieën.

Automatisch

Gebruik voor de meeste gevallen. De runtime bepaalt of statisch of dynamisch gedrag geschikt is op basis van renderingbehoeften.

Statisch

Gebruik wanneer de uitvoer niet afhankelijk is van veranderende gebruiker-, tijd- of request-gevoelige context.

Dynamisch

Gebruik wanneer de uitvoer afhankelijk is van vaak veranderende context en zich niet als een volledig cache-vriendelijk fragment moet gedragen.

Voorbeeld beslisregel:

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

Prestatieadvies

Variabelen worden vaak breed hergebruikt, dus prestatie-discpline is belangrijk.

geef de voorkeur aan auto of static tenzij er een echte reden voor dynamic is
vermijd kostbare query-intensieve uitvoer in fragmenten die op veel pagina's gebruikt worden
behandel veel gedeelde Variabelen als prestatiegevoelige assets
bekijk wijzigingsimpact voordat je een veel gebruikte Variabele wijzigt

Voorbeeld en Testen

Bij het testen van een Variabele, controleer:

rendering met realistische attributen
gedrag binnen de daadwerkelijke pagina- of componentcontext
uitvoer onder de beoogde cachemodus
genest gedrag van Variabelen als er compositie betrokken is

Voorbeeld testpatroon:

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

Wanneer een Variabele gebruiken

Gebruik een Variabele wanneer:

het fragment op meerdere plaatsen hergebruikt wordt
de structuur klein en stabiel is
de inputs beperkt zijn
de uitvoer contextbewust moet zijn

Gebruik geen Variabele wanneer:

de inhoud uniek is voor één Pagina
een volledig bewerkbaar schema vereist is
de structuur groot genoeg is om een herbruikbare sectie te zijn
de uitvoer in feite een dynamisch archief is in plaats van een fragment

Anti-patronen

Vermijd:

Variabelen veranderen in mini-pagina's
grote bedrijfsworkflows verbergen in één Variabele
te veel attributen toevoegen om een Component-schema te simuleren
diep geneste Variabele-ketens met onduidelijk eigenaarschap
de dynamic cache-modus standaard gebruiken zonder echte noodzaak

Voorbeeldpatronen

Klein utility-fragment:

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

Pagina-bewust herbruikbaar snippet:

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

Query-gedreven widget:

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

FaceFlow Variables — Reusable Template Fragments