Documentazione per sviluppatori dei Componenti

I componenti sono sezioni del sito guidate da uno schema e renderizzate tramite FaceFlow.

Per gli utenti tecnici, i componenti sono il contratto centrale di sezione riutilizzabile nel sistema. Combinano definizioni di campo, output del template Facet, stili opzionali, comportamento opzionale lato client e riuso consapevole dell'ambito.

Responsabilità principali

Un componente è responsabile di:

• definire un contratto di sezione riutilizzabile
• esporre uno schema di authoring controllato
• renderizzare l'output tramite Facet
• opzionalmente allegare stili e comportamenti con ambito limitato
• supportare il riuso a livello di pagina, layout o sito

I componenti dovrebbero risolvere problemi di sezione ripetibili. Non dovrebbero diventare contenitori generici per markup arbitrario specifico di una pagina.

Modello di definizione del componente

Una tipica definizione di Componente include:

{
  "name": "contact-section",
  "title": "Contact Section",
  "version": "1.0.0",
  "type": "component",
  "category": "contact",
  "defaultScope": "page",
  "description": "Contact section with CTA and embedded form support",
  "fields": [
    { "name": "title", "label": "Title", "type": "text" },
    { "name": "summary", "label": "Summary", "type": "textarea" },
    { "name": "contactForm", "label": "Form", "type": "formSelect" }
  ],
  "html": "<section><h2>{{ title }}</h2><p>{{ summary }}</p><div data-form-embed=\"{contactForm}\"></div></section>",
  "style": ".contact-section { padding: 4rem 0; }",
  "script": "/* optional behavior */"
}

Questo modello permette a un Componente di comportarsi come un contratto di sezione governato invece che come un frammento di codice copiato e scollegato.

Metadati principali

I campi di metadati importanti includono:

• name
• title
• version
• type
• category
• defaultScope
• description

Indicazioni:

• mantenere name stabile dopo il rilascio
• usare title per chiarezza nell'editor
• aggiornare version intenzionalmente quando lo schema o il comportamento di rendering cambiano
• scegliere defaultScope in base al riuso previsto, non per comodità

Schema dei campi

Lo schema dei campi definisce ciò che gli autori possono modificare senza alterare la struttura della sezione.

I tipi di campo di primo livello supportati includono:

• text
• textarea
• number
• url
• date
• image
• images
• file
• select
• checkbox
• richtext
• htmlcode
• map
• repeater
• formSelect
• reviewSelect

Tipi di sottocampo aggiuntivi possono essere usati all'interno di repeater, inclusi:

• color
• email
• tel
• range

Esempio:

{
  "name": "faqItems",
  "label": "FAQ Items",
  "type": "repeater",
  "fields": [
    { "name": "question", "type": "text" },
    { "name": "answer", "type": "textarea" }
  ]
}

Scegli i tipi di campo in base all'intento del contenuto, non per convenienza. Un url dovrebbe rimanere un URL. Un insieme ripetuto di card dovrebbe essere un repeater, non diversi campi di testo scollegati.

Vedi il riferimento completo dei campi:

• Campi dei Componenti
• Campo Repeater

Modello del template

La porzione html di un Componente è renderizzata tramite Facet.

Ciò significa che i template possono usare:

• output dei campi
• condizionali
• loop
• filtri
• contesto consapevole della pagina
• Variabili riutilizzabili

Esempio:

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

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

    {{#if ctaUrl}}
      <a href="{{ ctaUrl }}" class="btn-primary">{{ ctaLabel }}</a>
    {{/if}}
  </div>
</section>

Oppure con un repeater:

<div class="faq-list">
  {{#each faqItems as="item"}}
    <article class="faq-item">
      <h3>{{ item.question }}</h3>
      <p>{{ item.answer }}</p>
    </article>
  {{/each}}
</div>

Per dettagli sulla sintassi:

• Facet
• Sintassi dei template Facet

Modello di ambito

I componenti possono esistere a tre livelli di riuso:

• site
• layout
• page

Concettualmente:

site scope   -> reusable across the broader site
layout scope -> shared inside one page family
page scope   -> local to one page

L'ambito determina sia la visibilità sia l'impatto delle modifiche. Se un Componente cambia a livello site, quella è una modifica architetturale ampia, non una modifica locale.

Per il modello più ampio:

• Sistema di scope

Comportamento di rendering

Al momento del rendering, FaceFlow risolve l'istanza del Componente combinando:

• la definizione del Componente
• i valori dei campi salvati
• il contesto di rendering corrente
• servizi runtime correlati come media, Variabili, Moduli e Recensioni

Concettualmente:

component definition
  + saved field values
  + runtime context
  -> Facet render
  -> final section output

Questo è il punto in cui i dati dei campi diventano markup a runtime.

Stili e comportamento

I componenti possono allegare stili opzionali e comportamenti opzionali.

Esempio:

.pricing-card {
  border-radius: 1rem;
  padding: 2rem;
}

document.querySelectorAll('.faq-item button').forEach((button) => {
  button.addEventListener('click', () => {
    button.closest('.faq-item').classList.toggle('is-open');
  });
});

Usa questo con parsimonia. La maggior parte del comportamento della sezione dovrebbe rimanere semplice, prevedibile e facile da manutenere.

Moduli e recensioni all'interno dei componenti

Due tipi di campo sono particolarmente importanti per le sezioni interattive:

• formSelect
• reviewSelect

Questi permettono ai componenti di incorporare flussi di lavoro aziendali senza codificare rigidamente un modello specifico.

Marcatori tipici:

<div data-form-embed="{contactForm}"></div>
<div data-review-embed="{serviceReview}"></div>

Questo mantiene la sezione riutilizzabile pur consentendo al Modulo o al modello di Recensione selezionato di cambiare in fase di authoring.

Esempi di pattern per componenti

Basic content section:

fields:
  title
  summary
template:
  heading + paragraph

FAQ section:

fields:
  faqItems repeater
template:
  each item -> question + answer

Lead capture section:

fields:
  title
  summary
  contactForm (formSelect)
template:
  copy + data-form-embed marker

Checklist di revisione tecnica

• il Componente risolve un problema di sezione ripetibile?
• lo schema dei campi è chiaro e intenzionale?
• il template è leggibile e stabile?
• l'ambito scelto è corretto per il riuso previsto?
• un futuro editor capirebbe come usarlo solo dal contratto dei campi?

Pratiche da evitare

Evitare:

• sovraccaricare un singolo Componente con casi d'uso non correlati
• aggiungere logica aziendale specifica della pagina che dovrebbe rimanere fuori dal contratto di sezione
• usare htmlcode quando un modello di campo strutturato sarebbe più sicuro
• ampliare l'ambito solo perché la sezione potrebbe essere riutilizzata un giorno
• rinominare i campi dopo che i contenuti sono già stati memorizzati contro di essi

Quando separare un componente

Dividi un Componente quando:

• lo schema dei campi è diventato troppo ampio
• diversi layout o contesti di pagina necessitano versioni conflittuali
• il template è pieno di eccezioni e rami una tantum
• gli editor non capiscono più cosa la sezione dovrebbe fare

Se il contratto smette di essere chiaro, il riuso di solito smette di essere utile.

Correlati

• Panoramica del prodotto Componenti
• Guida ai Componenti
• Campi dei Componenti
• Pagine
• Layout
• Moduli
• Recensioni