Documentazione per sviluppatori delle Liste

Le Liste sono lo strato di contenuto dinamico in FaceFlow.

Consentono agli utenti tecnici di definire come le collezioni di contenuti vengono selezionate, renderizzate, paginate e pubblicate all'interno di un'esperienza Page senza convertire ogni archivio o directory in modifica manuale della pagina.

Responsabilità principali

Una Lista è responsabile di:

selezionare un insieme di contenuti
ordinare e limitare i risultati
renderizzare ogni elemento in modo coerente
paginare collezioni più grandi
esporre un contratto di navigazione prevedibile

Le Liste dovrebbero rispondere a una domanda chiara: "quale collezione è responsabile di essere presentata da questa pagina?"

Modello di Lista

Una Lista tipica combina:

una definizione di query
una strategia di ordinamento dei risultati
una dimensione di pagina
una modalità di rendering
campi personalizzati opzionali
logica opzionale del template dell'elemento

Concettualmente:

{
  "name": "resource-library",
  "query": {
    "template": "resource-item",
    "parent": "/resources/",
    "sort": "-published",
    "limit": 12
  },
  "display": {
    "mode": "custom-template",
    "pagination": true
  }
}

Contratto di query

I team tecnici dovrebbero mantenere le query delle Liste esplicite e delimitate.

Gli input tipici includono:

tipo di contenuto
confine della sezione
ordinamento
limite dei risultati
vincoli di filtro aggiuntivi

Una query debole genera un output debole. Se il confine dei contenuti è vago, la Lista diventa rapidamente un deposito indiscriminato.

Esempio:

template=resource-item, parent=/resources/, sort=-published, limit=12

Quella query è comprensibile. Un archivio generico che include vari tipi non correlati di solito non lo è.

Esempio di progettazione della query

Le buone definizioni di Lista solitamente mantengono separate la regola di selezione e la regola di visualizzazione:

{
  "name": "case-studies",
  "query": {
    "template": "case-study",
    "parent": "/customers/",
    "sort": "-published",
    "limit": 9
  },
  "display": {
    "mode": "custom-template",
    "pagination": true
  }
}

Questo rende più semplice verificare se il confine dei contenuti è corretto prima di discutere la presentazione.

Modalità di rendering

Le Liste seguono generalmente uno dei due modelli.

Output in stile scheda

Usa questo quando:

gli editor necessitano di un percorso di configurazione semplice
l'archivio segue uno schema visivo standard
un formato di scheda coerente è sufficiente

Output con template personalizzato

Usa questo quando:

gli elementi dei risultati necessitano di una mappatura più ricca
il design non è una semplice griglia di schede
i metadati, i badge o i media richiedono un posizionamento personalizzato
l'archivio dipende dalla logica di Facet

Esempio di output personalizzato per elemento:

<div class="resource-grid">
  {{#each items}}
    <article class="resource-card">
      <a href="{{ this.url }}">
        <h3>{{ this.title }}</h3>
        <p>{{ this.summary }}</p>
      </a>
    </article>
  {{/each}}
</div>

Paginazione

La paginazione fa parte del contratto della Lista, non è solo un dettaglio visivo.

La revisione tecnica dovrebbe definire:

dimensione di pagina predefinita
comportamento del conteggio delle pagine
schema di navigazione
comportamento in caso di stato vuoto

Concettualmente:

page 1 -> items 1-12
page 2 -> items 13-24
page 3 -> items 25-36

Se ci si aspetta che una Lista cresca, la paginazione dovrebbe essere intenzionale fin dalla prima versione.

Relazione con Pagine e Componenti

Il modello mentale chiaro è:

Layout fornisce la struttura di base
Pagina fornisce la rotta pubblicabile e l'esperienza circostante
Lista fornisce la collezione dinamica
Componente può fornire sezioni di supporto attorno alla Lista

Esempio di composizione della pagina:

resource-layout
  -> archive-hero component
  -> resource-library list
  -> newsletter-signup component

Questo mantiene la navigazione dinamica separata dai contenuti della pagina non ricorrenti.

Esempio di template per Lista

<section class="archive">
  <header class="archive-header">
    <h1>{{ page.title }}</h1>
  </header>

  <div class="archive-items">
    {{#each items}}
      <article class="archive-item">
        <a href="{{ this.url }}">{{ this.title }}</a>
      </article>
    {{/each}}
  </div>

  {{#if pagination}}
    <nav class="archive-pagination">
      {{{ pagination.links }}}
    </nav>
  {{/if}}
</section>

L'obiettivo è un contratto stabile tra la query della Lista e il template dell'archivio.

Regole per stato vuoto e crescita

La revisione tecnica dovrebbe anche considerare cosa accade quando la collezione cambia forma:

nessun risultato
un risultato
molte pagine di risultati
campi opzionali mancanti su alcuni elementi

Un template di Lista è stabile solo se resiste a tutte e quattro le condizioni senza rotture del layout o output confusi.

Checklist per la revisione tecnica

il confine della query è chiaro e ristretto?
l'ordinamento corrisponde all'intento di navigazione?
il template può gestire la crescita del volume dei risultati?
la paginazione fa parte del contratto di design?
la Lista risolve un singolo problema d'archivio, non diversi problemi non correlati?

Pratiche da evitare

Evitare:

mescolare tipi di contenuto non correlati in un archivio solo perché sono disponibili
realizzare un archivio completamente a mano con schede ripetute
usare una sola Lista per più modalità visive con contratti incompatibili
lasciare l'ordinamento dei risultati implicito
ignorare gli stati vuoti e la paginazione fino a quando il volume dei contenuti non diventa un problema

FaceFlow Lists — Dynamic Content Listings