Listen — Entwicklerdokumentation

Listen sind die dynamische Inhaltsebene in FaceFlow.

Sie ermöglichen es technischen Anwendern zu definieren, wie Inhaltskollektionen innerhalb einer Page-Erfahrung ausgewählt, gerendert, paginiert und veröffentlicht werden, ohne jedes Archiv oder Verzeichnis in manuelle Seitenbearbeitung umzuwandeln.

Kernaufgabe

Eine Liste ist verantwortlich für:

die Auswahl einer Inhaltsmenge
das Sortieren und Begrenzen der Ergebnisse
das konsistente Rendern jedes Elements
das Paginieren größerer Sammlungen
das Bereitstellen eines vorhersehbaren Browsing-Vertrags

Listen sollten eine klare Frage beantworten: „Welche Sammlung soll diese Seite präsentieren?“

Listenmodell

Eine typische Liste kombiniert:

eine Abfrage-Definition
eine Ergebnis-Sortierstrategie
eine Seitengröße
einen Darstellungsmodus
optionale benutzerdefinierte Felder
optionale Template-Logik für Elemente

Konzeptionell:

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

Abfragevertrag

Technische Teams sollten Listenabfragen explizit und begrenzt halten.

Typische Eingaben umfassen:

Inhaltstyp
Abschnittsgrenze
Sortierung
Ergebnisslimit
zusätzliche Filterbedingungen

Eine schwache Abfrage erzeugt schwache Ergebnisse. Wenn die Inhaltsgrenze vage ist, wird die Liste schnell zu einer Ablage.

Beispiel:

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

Diese Abfrage ist verständlich. Ein Catch-all-Archiv mit mehreren nicht zusammenhängenden Typen ist es normalerweise nicht.

Beispiel für Abfragedesign

Gute List-Definitionen trennen meist die Auswahlregel und die Darstellungsregel:

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

So lässt sich leichter prüfen, ob die Inhaltsgrenze korrekt ist, bevor die Präsentation besprochen wird.

Darstellungsmodi

Listen folgen normalerweise einem von zwei Modellen.

Ausgabe im Kartenstil

Verwenden Sie dies, wenn:

Redakteure einen reibungslosen Konfigurationspfad benötigen
das Archiv einem Standard-Visuellen Muster folgt
ein konsistentes Karten-Layout ausreicht

Benutzerdefinierte Template-Ausgabe

Verwenden Sie dies, wenn:

Ergebnis-Elemente eine reichere Zuordnung benötigen
das Design kein einfaches Kartenraster ist
Metadaten, Abzeichen oder Medien eine benutzerdefinierte Platzierung benötigen
das Archiv von Facet-Logik abhängt

Beispiel einer benutzerdefinierten Elementausgabe:

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

Paginierung

Paginierung ist Teil des Listenvertrags, nicht nur ein visuelles Detail.

Die technische Prüfung sollte definieren:

Standardseitengröße
Verhalten bei Seitenanzahl
Navigationsmuster
Verhalten im Leerzustand

Konzeptionell:

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

Wenn erwartet wird, dass eine Liste wächst, sollte Paginierung von der ersten Veröffentlichung an bewusst vorgesehen sein.

Beziehung zu Seiten und Komponenten

Das klare Denkmodell ist:

Layout stellt das Grundgerüst bereit
Seite stellt die veröffentlichbare Route und die umgebende Erfahrung bereit
Liste stellt die dynamische Sammlung bereit
Komponente kann unterstützende Abschnitte um die Liste herum bereitstellen

Beispielhafte Seitenzusammensetzung:

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

Das trennt dynamisches Browsing von einmaligen Seiteninhalten.

Beispiel für eine Listenvorlage

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

Das Ziel ist ein stabiler Vertrag zwischen der Listenabfrage und der Archivvorlage.

Regeln für Leerzustand und Wachstum

Die technische Prüfung sollte außerdem berücksichtigen, was passiert, wenn sich die Sammlung verändert:

keine Ergebnisse
ein Ergebnis
viele Seiten mit Ergebnissen
fehlende optionale Felder bei einigen Elementen

Eine Listenvorlage ist nur dann stabil, wenn sie alle vier Zustände übersteht, ohne Layout-Brüche oder verwirrende Ausgaben zu erzeugen.

Technische Prüfliste

Ist die Abfragegrenze klar und eng gefasst?
Passt die Sortierung zur Browsing-Absicht?
Kann das Template mit steigendem Ergebnisvolumen umgehen?
Ist Paginierung Teil des Designvertrags?
Löst die Liste ein Archivproblem und nicht mehrere nicht zusammenhängende?

Anti-Patterns

Vermeiden Sie:

das Mischen nicht zusammenhängender Inhaltstypen in einem Archiv nur weil sie verfügbar sind
den Aufbau eines Archivs komplett von Hand mit wiederholten manuellen Karten
die Verwendung einer Liste für mehrere visuelle Modi mit inkompatiblen Verträgen
das Belassen der Ergebnisreihenfolge als implizit
das Ignorieren von Leerzuständen und Paginierung, bis das Inhaltsvolumen zum Problem wird

FaceFlow Lists — Dynamic Content Listings