Lijst-ontwikkelaarsdocumentatie

Lijsten zijn de dynamische contentlaag in FaceFlow.

Ze stellen technische gebruikers in staat te definiëren hoe contentcollecties worden geselecteerd, gerenderd, gepagineerd en gepubliceerd binnen een Page-ervaring zonder elk archief of elke directory om te zetten naar handmatige paginabewerking.

Kernverantwoordelijkheid

Een Lijst is verantwoordelijk voor:

het selecteren van een contentset
het sorteren en beperken van resultaten
elk item consistent renderen
grotere collecties pagineren
het bieden van een voorspelbaar bladercontract

Lijsten moeten één duidelijke vraag beantwoorden: "Welke collectie moet deze pagina presenteren?"

Lijst-model

Een typische Lijst combineert:

een querydefinitie
een strategie voor ordening van resultaten
een paginagrootte
een weergavemodus
optionele aangepaste velden
optionele sjabloonlogica voor items

Conceptueel:

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

Querycontract

Technische teams moeten Lijst-queries expliciet en begrensd houden.

Typische invoer omvat:

contenttype
sectiegrens
sortering
resultaatlimiet
aanvullende filterbeperkingen

Een zwakke query creëert zwakke output. Als de contentgrens vaag is, wordt de Lijst snel een stortplaats.

Voorbeeld:

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

Die query is begrijpelijk. Een allesomvattend archief met meerdere niet-gerelateerde types is dat meestal niet.

Voorbeeld van queryontwerp

Goede Lijst-definities houden meestal de selectieregel en weergaveregel gescheiden:

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

Dat maakt het makkelijker om te beoordelen of de contentgrens correct is voordat presentatie wordt besproken.

Weergavemodi

Lijsten volgen meestal een van twee modellen.

Kaartstijlweergave

Gebruik dit wanneer:

redacteuren een laagdrempelige configuratieprocedure nodig hebben
het archief een standaard visueel patroon volgt
één consistent kaartcontract voldoende is

Aangepaste sjabloonuitvoer

Gebruik dit wanneer:

resultaatitems een rijkere mapping nodig hebben
het ontwerp geen eenvoudig kaartraster is
metadata, badges of media aangepaste plaatsing nodig hebben
het archief afhankelijk is van Facet-logica

Voorbeeld van aangepaste itemuitvoer:

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

Paginering

Paginering is onderdeel van het Lijst-contract, niet alleen een visueel detail.

Technische beoordeling moet definiëren:

standaard paginagrootte
gedrag bij paginatelling
navigatiepatroon
gedrag bij lege toestand

Conceptueel:

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

Als een Lijst naar verwachting groeit, moet paginering vanaf de eerste release doelbewust worden toegepast.

Relatie met Pagina's en Componenten

Het heldere mentale model is:

Lay-out biedt de shell
Pagina biedt de publiceerbare route en de omringende ervaring
Lijst biedt de dynamische collectie
Component kan ondersteunende secties rond de Lijst bieden

Voorbeeld van paginasamenstelling:

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

Dit houdt dynamisch bladeren gescheiden van eenmalige paginacontent.

Voorbeeld van Lijst-sjabloon

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

Het doel is een stabiel contract tussen de Lijst-query en de archiefsjabloon.

Regels voor lege toestand en groei

Technische beoordeling moet ook rekening houden met wat er gebeurt wanneer de collectie van vorm verandert:

geen resultaten
één resultaat
veel pagina's met resultaten
ontbrekende optionele velden bij sommige items

Een Lijst-sjabloon is alleen stabiel als het alle vier de condities overleeft zonder lay-outbreuk of verwarrende output.

Checklist voor technische beoordeling

is de querygrens duidelijk en beperkt?
komt de sortering overeen met de bedoeling van het bladeren?
kan de sjabloon omgaan met toename van het aantal resultaten?
is paginering onderdeel van het ontwerpcontract?
lost de Lijst één archiefprobleem op, niet meerdere niet-gerelateerde?

Anti-patronen

Vermijd:

het mengen van niet-gerelateerde contenttypes in één archief alleen omdat ze beschikbaar zijn
het archief volledig met de hand opbouwen met herhaalde handmatige kaarten
één Lijst gebruiken voor meerdere visuele modi met incompatibele contracten
het ordenen van resultaten impliciet laten
lege toestanden en paginering negeren totdat het volume content een probleem wordt

FaceFlow Lists — Dynamic Content Listings