🇩🇪 Deutsch 🇺🇸 English 🇪🇸 Español 🇫🇷 Français 🇮🇹 Italiano 🇳🇱 Nederlands 🇵🇹 Português
🇩🇪 Deutsch 🇺🇸 English 🇪🇸 Español 🇫🇷 Français 🇮🇹 Italiano 🇳🇱 Nederlands 🇵🇹 Português

Facet Template Engine — Developer Guide

Facet is the core rendering engine of FaceFlow.

Documentazione per sviluppatori di Facet

Facet è il livello di template usato da FaceFlow per il rendering dinamico.

Fornisce agli utenti tecnici un modo controllato per emettere valori, comporre frammenti di template riutilizzabili, lavorare con cicli e condizioni, e costruire logiche di visualizzazione dinamica all'interno di PageFace.

A cosa serve Facet

  • template dei componenti
  • template delle variabili
  • output dinamico di liste
  • rendering di contenuti condivisi
  • output contestuale della pagina

Facet non è l'intero sistema FaceFlow. È il linguaggio di rendering al suo interno. FaceFlow definisce gli oggetti e i contratti. Facet definisce come quegli oggetti producono output dinamico in modo sicuro.

Funzionalità principali

Gli utenti tecnici tipicamente si affidano a Facet per:

  • output escapato e raw
  • blocchi condizionali e cicli
  • rendering consapevole della pagina e delle query
  • catene di filtri e formattazione
  • inserimento di variabili
  • composizione sicura dei template all'interno di oggetti riutilizzabili

Facet vs FaceFlow

Mantieni chiaro questo confine:

  • FaceFlow definisce oggetti come Pagine, Componenti, Variabili, Liste, Moduli e Recensioni
  • Facet definisce come quegli oggetti producono output dinamico

Se un utente tecnico sta decidendo quale oggetto creare, si trova nell'ambito di design di FaceFlow.

Se sta decidendo come un oggetto esistente debba renderizzare campi, condizioni e cicli, si trova nell'ambito di Facet.

Dove appare

Facet appare comunemente in:

  • template HTML dei Componenti
  • template delle Variabili
  • template degli elementi di Lista
  • frammenti dinamici più piccoli che necessitano del contesto a runtime

Un esempio semplice:

<section class="hero">
  <h1>{{ title }}</h1>

  {{#if summary}}
    <p>{{ summary }}</p>
  {{/if}}

  [[sales-contact-badge]]
</section>

Questo esempio mostra il modello mentale più comune:

  • L'oggetto FaceFlow fornisce il contratto
  • Facet fornisce la logica di rendering

Cosa Facet non dovrebbe fare

Facet è potente, ma non dovrebbe diventare un sostituto di una buona modellazione degli oggetti.

Non usare Facet per:

  • nascondere una struttura dei contenuti debole dietro trucchi del template
  • trasformare un template in un motore di workflow aziendale
  • sostituire le Liste con logica di archivio scritta a mano quando il problema è in realtà contenuto guidato da query
  • simulare uno schema modificabile esteso che dovrebbe essere un Componente

Come imparare Facet

Segui questo percorso di lettura:

  1. inizia con Sintassi dei template
  2. prosegui con Riferimento
  3. poi torna all'oggetto FaceFlow che possiede il template che stai modificando

Quest'ordine funziona perché prima viene la sintassi, poi i pattern più profondi e infine l'applicazione specifica dell'oggetto.

Casi d'uso comuni

Gli utenti tecnici tipicamente ricorrono a Facet quando devono:

  • mostrare campi opzionali in modo pulito
  • iterare su contenuti ripetuti
  • formattare valori consapevoli della pagina
  • incorporare Variabili riutilizzabili
  • costruire template di archivio e lista senza codice raw della piattaforma

Errori comuni

Gli utenti tecnici incontrano più spesso problemi quando:

  • spingono troppa logica in un unico template
  • trattano un frammento ripetuto come markup copiato invece che come Variabile
  • usano condizionali per compensare un modello di campo poco chiaro
  • costruiscono un archivio dinamico in un Componente quando dovrebbe essere una Lista
  • dimenticano che la leggibilità fa parte della qualità del template

Linee guida di progettazione

  • mantieni i template leggibili
  • mantieni la logica di business superficiale
  • preferisci una forte modellazione degli oggetti rispetto a trucchi intelligenti nel template
  • usa le Variabili per i frammenti ripetuti invece di copiare il markup
  • usa le Liste quando il problema è la selezione dinamica dei contenuti, non solo la visualizzazione

Scorciatoia decisionale

Usa Facet quando la domanda suona come:

  • "come dovrebbe renderizzare questo campo?"
  • "questa sezione dovrebbe mostrarsi solo quando esistono dati?"
  • "come faccio a iterare su questi elementi?"
  • "come riutilizzo questo piccolo frammento?"

Non fermarti a Facet quando la domanda è davvero:

  • "dovrebbe essere un Componente o una Variabile?"
  • "questo contenuto dovrebbe essere una Lista?"
  • "appartiene al Layout o alla Pagina?"

Correlati