Documentazione per sviluppatori: Variabili

Le Variabili sono frammenti riutilizzabili basati su template resi all'interno di contesti gestiti da FaceFlow.

Per gli utenti tecnici, le Variabili sono uno dei primitivi di riuso più leggeri in FaceFlow. Sono appropriate quando l'output deve essere condiviso tra layout, componenti, liste o altre superfici di rendering senza introdurre uno schema completo di Componente.

Responsabilità principali

Una Variabile è responsabile di:

output riutilizzabile basato su template
eventuale CSS e comportamento lato client
semplice parametrizzazione tramite attributi
rendering consapevole del contesto
consegna sensibile alla cache per output ripetuti

Usa una Variabile quando l'unità di riuso è più piccola di un Componente ma più duratura del markup copiato.

Modello di una Variabile

Una Variabile tipica include:

un'identità stabile
un template Facet
CSS opzionale
JavaScript opzionale
attributi opzionali
metadati di categoria e descrizione
una modalità di cache

Concettualmente:

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

L'implementazione esatta dello storage è interna. Il contratto sopra è la parte importante per gli autori tecnici.

Sintassi di incorporamento

Le Variabili vengono incorporate con la sintassi a doppia parentesi quadra:

[[copyright-notice]]

Con attributi:

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

Le Variabili possono anche essere incorporate all'interno di altri template:

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

I valori degli attributi devono essere passati come letterali racchiusi tra virgolette nella sintassi di incorporamento.

Se una Variabile ha bisogno di comportamento sensibile alla pagina o al runtime, leggi dal contesto di rendering all'interno del template della Variabile invece di cercare di iniettare un'espressione non quotata nella lista degli attributi.

Modello degli attributi

Gli attributi sono input nominati passati alla Variabile al momento del rendering.

Sono adatti per:

varianti di testo
etichette
opzioni visive semplici
piccoli valori specifici per il business

Esempio:

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

Uso nel template:

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

Gli attributi dovrebbero rimanere leggeri. Se l'unità di riuso necessita di uno schema editabile ampio, questo normalmente indica un Componente.

Esempio di miscelazione sicura di attributi letterali con il contesto di runtime:

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

Contesto di rendering

Le Variabili possono essere renderizzate rispetto a un contesto di runtime più ampio. Gli oggetti di contesto comuni includono:

page
user
pages
site
languages / lang
now
attr

Esempio:

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

Oppure un esempio guidato da query:

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

Questo è ciò che rende le Variabili utili per piccoli frammenti dinamici senza richiedere una Lista o un Componente completo.

Posizionamento supportato

Le Variabili sono comunemente usate in:

template di layout
template di componente
template di lista
altre Variabili
superfici di contenuto supportate che passano attraverso il rendering di FaceFlow

Esempi tipici:

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

Annidamento

Le Variabili possono fare riferimento ad altre Variabili:

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

L'annidamento è utile quando migliora la chiarezza. Evita catene profonde che rendono difficile il debug o la valutazione dell'impatto delle modifiche.

Modalità di cache

Le Variabili supportano più strategie di cache.

Auto

Usa questa modalità nella maggior parte dei casi. Il runtime determina se un comportamento statico o dinamico è appropriato in base alle esigenze di rendering.

Statico

Usa questa modalità quando l'output non dipende da un contesto utente, temporale o di richiesta variabile.

Dinamico

Usa questa modalità quando l'output dipende da un contesto che cambia frequentemente e non dovrebbe comportarsi come un frammento completamente cache-friendly.

Example decision rule:

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

Linee guida sulle prestazioni

Le Variabili sono spesso riutilizzate ampiamente, quindi la disciplina sulle prestazioni è importante.

preferisci auto o static a meno che non ci sia una reale ragione per dynamic
evita output costosi e con query pesanti in frammenti usati su molte pagine
tratta le Variabili ampiamente condivise come asset sensibili alle prestazioni
rivedi l'impatto delle modifiche prima di modificare una Variabile molto riutilizzata

Anteprima e test

Quando testi una Variabile, verifica:

il rendering con attributi realistici
il comportamento all'interno del contesto reale della pagina o del componente
l'output sotto la modalità di cache prevista
il comportamento delle Variabili annidate se è coinvolta la composizione

Esempio di pattern di test:

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

Quando usare una Variabile

Usa una Variabile quando:

il frammento è riutilizzato in diversi punti
la struttura è piccola e stabile
gli input sono limitati
l'output necessita di consapevolezza del contesto

Non usare una Variabile quando:

il contenuto è unico per una sola Pagina
è richiesto uno schema editabile completo
la struttura è sufficientemente ampia da costituire una sezione riutilizzabile
l'output è in realtà un archivio dinamico piuttosto che un frammento

Pratiche da evitare

Evita:

trasformare le Variabili in mini-pagine
nascondere grandi workflow di business all'interno di una sola Variabile
aggiungere troppi attributi per simulare uno schema di Componente
catene di Variabili profondamente annidate con proprietà poco chiare
usare la modalità di cache dynamic come impostazione predefinita senza una reale necessità

Esempi di pattern di costruzione

Small utility fragment:

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

Page-aware reusable snippet:

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

Query-driven widget:

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

FaceFlow Variables — Reusable Template Fragments