Documentation developpeur Variable

Les Variables sont des fragments reutilisables pilotes par template, rendus dans des contextes geres par FaceFlow.

Pour les utilisateurs techniques, les Variables sont l'une des primitives de reutilisation les plus legeres dans FaceFlow. Elles conviennent lorsque la sortie doit etre partagee entre des layouts, des components, des lists ou d'autres surfaces de rendu sans introduire un schema complet de Component.

Responsabilite centrale

Une Variable est responsable de :

• la sortie de template reutilisable
• un CSS optionnel et un comportement cote client optionnel
• une parametrisation simple via des attributs
• un rendu conscient du contexte
• une livraison sensible au cache pour les sorties repetees

Utilisez une Variable quand l'unite de reutilisation est plus petite qu'un Component mais plus durable qu'un simple copier-coller de markup.

Modele de Variable

Une Variable typique comprend :

• une identite stable
• un template Facet
• un CSS optionnel
• un JavaScript optionnel
• des attributs optionnels
• des metadonnees de categorie et de description
• un mode de cache

Conceptuellement :

{
  "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'implementation exacte de stockage reste interne. Le contrat ci-dessus est la partie importante pour les auteurs techniques.

Syntaxe d'inclusion

Les Variables sont incluses avec la syntaxe a doubles crochets :

[[copyright-notice]]

Avec attributs :

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

Les Variables peuvent aussi etre incluses dans d'autres templates :

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

Les valeurs d'attribut doivent etre passees comme litteraux entre guillemets dans la syntaxe d'inclusion.

Si une Variable a besoin d'un comportement dependant de la page ou du runtime, lisez le contexte de rendu dans le template de la Variable plutot que d'essayer d'injecter une expression non quotee dans la liste d'attributs.

Modele d'attributs

Les attributs sont des entrees nommees passees a la Variable au moment du rendu.

Ils conviennent pour :

• des variantes de copy
• des labels
• de petites options visuelles
• de petites valeurs specifiques au metier

Exemple :

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

Usage dans le template :

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

Les attributs doivent rester legers. Si l'unite reutilisable a besoin d'un schema editable large, cela indique en general qu'il faut plutot un Component.

Exemple de combinaison sure entre attributs litteraux et contexte runtime :

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

Contexte de rendu

Les Variables peuvent etre rendues avec un contexte runtime plus large. Les objets de contexte frequents incluent :

• page
• user
• pages
• site
• languages / lang
• now
• attr

Exemple :

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

Ou un exemple pilote par requete :

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

C'est ce qui rend les Variables utiles pour de petits fragments dynamiques sans necessiter une List ou un Component complet.

Surfaces compatibles

Les Variables sont couramment utilisees dans :

• les templates de Layout
• les templates de Component
• les templates de List
• d'autres Variables
• les surfaces compatibles qui passent par le rendu FaceFlow

Exemples typiques :

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

Imbrication

Les Variables peuvent referencer d'autres Variables :

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

L'imbrication est utile lorsqu'elle ameliore la clarte. Evitez les chaines trop profondes qui rendent le debug ou l'impact des changements difficiles a comprendre.

Modes de cache

Les Variables prennent en charge plusieurs strategies de cache.

Auto

A utiliser dans la plupart des cas. Le runtime determine si un comportement statique ou dynamique convient selon les besoins de rendu.

Static

A utiliser lorsque la sortie ne depend pas d'un utilisateur changeant, du temps ou d'un contexte sensible a la requete.

Dynamic

A utiliser lorsque la sortie depend d'un contexte qui change souvent et ne doit pas se comporter comme un fragment entierement compatible cache.

Regle de decision :

pied de page avec annee courante -> auto
texte juridique partage simple -> static
salutation utilisateur connecte -> dynamic

Conseils de performance

Les Variables sont souvent reutilisees largement, donc la discipline de performance compte.

• preferez auto ou static sauf raison reelle d'utiliser dynamic
• evitez les sorties couteuses ou riches en requetes dans des fragments utilises sur de nombreuses pages
• traitez les Variables largement partagees comme des actifs sensibles a la performance
• revoyez l'impact des changements avant d'editer une Variable tres reutilisee

Apercu et test

Quand vous testez une Variable, verifiez :

• le rendu avec des attributs realistes
• le comportement dans le contexte reel de page ou de component
• la sortie selon le mode de cache vise
• le comportement des Variables imbriquees si une composition est impliquee

Exemple de pattern de test :

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

Quand utiliser une Variable

Utilisez une Variable quand :

• le fragment est reutilise a plusieurs endroits
• la structure est petite et stable
• les entrees sont limitees
• la sortie doit etre consciente du contexte

N'utilisez pas une Variable quand :

• le contenu est unique a une seule Page
• un schema editable complet est requis
• la structure est assez grande pour devenir une section reutilisable
• la sortie est en realite une archive dynamique plutot qu'un fragment

Anti-patterns

Evitez :

• de transformer les Variables en mini-pages
• de cacher de gros workflows metier dans une seule Variable
• d'ajouter trop d'attributs pour simuler le schema d'un Component
• des chaines de Variables imbriquees trop profondes avec une propriete peu claire
• d'utiliser dynamic par defaut sans besoin reel

Exemples de construction

Petit fragment utilitaire :

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

Extrait reutilisable conscient de la page :

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

Widget pilote par requete :

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

Related

• Facet
• Components
• Lists
• Vue produit Variables