Documentation developpeur List

Les Lists sont la couche de contenu dynamique dans FaceFlow.

Elles permettent aux utilisateurs techniques de definir comment des collections de contenu sont selectionnees, rendues, paginees et publiees dans une experience de Page sans convertir chaque archive ou repertoire en edition de page manuelle.

Responsabilite centrale

Une List est responsable de :

• selectionner un ensemble de contenu
• trier et limiter les resultats
• rendre chaque element de facon coherente
• paginer les grandes collections
• exposer un contrat de navigation previsible

Les Lists doivent repondre a une question claire : "quelle collection cette page est-elle responsable de presenter ?"

Modele de List

Une List typique combine :

• une definition de requete
• une strategie d'ordre des resultats
• une taille de page
• un mode de rendu
• des champs personnalises optionnels
• une logique de template d'item optionnelle

Conceptuellement :

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

Contrat de requete

Les equipes techniques doivent garder les requetes de List explicites et bornees.

Les entrees typiques incluent :

• le type de contenu
• la limite de section
• le tri
• la limite de resultats
• des contraintes de filtre supplementaires

Une requete faible cree une sortie faible. Si la frontiere du contenu est vague, la List devient vite un depot sans structure.

Exemple :

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

Cette requete est comprehensible. Une archive fourre-tout avec plusieurs types sans lien ne l'est en general pas.

Exemple de conception de requete

Les bonnes definitions de List gardent en general la regle de selection et la regle d'affichage separees :

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

Cela facilite la revue de la bonne frontiere de contenu avant de discuter de la presentation.

Modes de rendu

Les Lists suivent en general l'un de deux modeles.

Sortie de type carte

A utiliser quand :

• les editeurs ont besoin d'une configuration simple
• l'archive suit un pattern visuel standard
• un contrat de carte coherent suffit

Sortie via template personnalise

A utiliser quand :

• les items ont besoin d'un mapping plus riche
• le design n'est pas une simple grille de cartes
• des metadonnees, badges ou medias necessitent un placement personnalise
• l'archive depend de la logique Facet

Exemple de sortie personnalisee :

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

Pagination

La pagination fait partie du contrat de la List, pas seulement d'un detail visuel.

La revue technique doit definir :

• la taille de page par defaut
• le comportement du nombre de pages
• le pattern de navigation
• le comportement d'etat vide

Conceptuellement :

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

Si une List doit grandir, la pagination doit etre intentionnelle des la premiere version.

Relation avec Pages et Components

Le modele mental propre est :

• Layout fournit la coquille
• Page fournit la route publiable et l'experience environnante
• List fournit la collection dynamique
• Component peut fournir les sections de support autour de la List

Exemple de composition de page :

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

Cela garde la navigation dynamique separee du contenu ponctuel d'une page.

Exemple de template de List

<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'objectif est un contrat stable entre la requete de List et le template d'archive.

Regles d'etat vide et de croissance

La revue technique doit aussi prendre en compte ce qui se passe lorsque la collection change de forme :

• aucun resultat
• un seul resultat
• plusieurs pages de resultats
• des champs optionnels manquants sur certains items

Un template de List n'est stable que s'il survit a ces quatre conditions sans casser la mise en page ni produire une sortie confuse.

Checklist de revue technique

• la frontiere de la requete est-elle claire et etroite ?
• le tri correspond-il a l'intention de navigation ?
• le template peut-il absorber une croissance du volume de resultats ?
• la pagination fait-elle partie du contrat de design ?
• la List resout-elle un seul probleme d'archive et non plusieurs sujets sans rapport ?

Anti-patterns

Evitez :

• de melanger des types de contenu sans rapport dans une seule archive simplement parce qu'ils sont disponibles
• de construire une archive entierement a la main avec des cartes repetees manuellement
• d'utiliser une seule List pour plusieurs modes visuels aux contrats incompatibles
• de laisser l'ordre des resultats implicite
• d'ignorer les etats vides et la pagination jusqu'a ce que le volume de contenu pose probleme

Related

• Vue produit Lists
• Guide List
• Pages
• Facet
• Media