Content-Pool-Inhalte eines Blocks:
blättern, sortieren, filtern

Ein Inhaltselement, das mit einem Content Pool verbunden ist, liefert seine Einträge normalerweise vollständig in items aus, als Teil der Seite. Bei einem Pool mit hunderten Einträgen wird die Seite dadurch gross, und alles hinter dem Limit ist für dein Frontend nicht erreichbar.

Als Collection liefert dasselbe Inhaltselement nur die erste Seite der Einträge mit der Seite aus. Alle weiteren Seiten lädt dein Frontend über den Collection-Endpunkt, auf Wunsch sortiert und gefiltert. Diese Seite richtet sich an Entwickler:innen.

• Aktivieren
• Der Schlüssel einer Collection
• Limit und Sortierung des Editors
• Das Objekt collection
• Der Collection-Endpunkt
• Sortieren
• Filtern
• Der Token einer Collection

Aktivieren

Die Collection schaltest du in der Definition des Inhaltselements ein, im Bereich Verbinden unter den Mapping-Feldern:

• Einträge als Collection ausliefern schaltet die Funktion ein.
• Einträge pro Seite legt fest, wie viele Einträge eine Seite hat: zwischen 1 und 100, standardmässig 24. Der Wert gilt für jede Seite, auch für die erste, die mit der Seite ausgeliefert wird. Eine Anfrage kann keine andere Seitengrösse verlangen.
• Erste Seite mit der Seite ausliefern ist standardmässig eingeschaltet. Schalte es aus, wenn dein Frontend die Einträge ohnehin selbst lädt, zum Beispiel erst nach einer Eingabe: items ist dann in der Seite leer.

Die Mapping-Felder werden zu den Feldern, nach denen dein Frontend sortiert und filtert. Ihre Identifier dürfen deshalb nicht mit _ beginnen und nicht position heissen. Felder mit einem einfachen Ausgabetyp (Text, Zahl, Datum, Datum und Zeit, Checkbox) sind im Editor als sortierbar markiert.

Der Schlüssel einer Collection

Jede Platzierung des Inhaltselements ist eine eigene Collection mit einem eigenen Schlüssel. Er ist der letzte Teil ihrer URL, /nitro/v1/blocks/collection/{key}, und steht im Seiteneditor im Reiter Verbinden des Blocks. Zu Beginn ist es die UID der Platzierung. Über das Schloss lässt er sich ändern, zum Beispiel in news-data, wenn du einen sprechenden Namen willst oder eine URL ablösen musst. Ein Schlüssel besteht aus Kleinbuchstaben, Ziffern, - und _, beginnt mit einem Buchstaben oder einer Ziffer und ist pro Sprache eindeutig: zwei Blöcke mit demselben Schlüssel lassen sich nicht speichern.

Wer einen Block kopiert, erhält eine neue Collection mit neuem Schlüssel. Ändert jemand den Schlüssel, ändert sich die URL, und Links, die dein Frontend gespeichert hat, laufen ins Leere.

Limit und Sortierung des Editors

Was der Editor in der Platzierung einstellt, gilt für die ganze Collection:

• Die Sortierung ist die Standardreihenfolge der Einträge. In der API heisst sie position.
• Das Limit bestimmt, welche Einträge zur Collection gehören. Bei einem Limit von 50 hat die Collection 50 Einträge, verteilt auf die Seiten, und ein Filter sucht nur in diesen 50 und nicht im ganzen Content Pool.

Das Objekt collection

Jedes Inhaltselement einer Seite trägt das Objekt collection, auch eines ohne Collection. So liest dein Frontend auf jedem Block dieselben Felder.

{
  "uid": "9b1c5e2a-4f0d-4c7e-8a51-2d6f3e7b9c10",
  "identifier": "news_list",
  "component": "NewsList",
  "content": { "title": "Aktuelles", "_empty": false },
  "config": { "_empty": true },
  "slots": { "_empty": true },
  "items": [
    { "title": "Neue Ausstellung im Kunsthaus", "category": { "value": "kultur", "label": "Kultur" }, "link": { "entity_unique_id": "a1b2c3d4e5", "entity_slug": "neue-ausstellung-im-kunsthaus" } }
  ],
  "collection": {
    "enabled": true,
    "key": "news-data",
    "per_page": 24,
    "inline_first_page": true,
    "total": 512,
    "page_count": 22,
    "current_page": 1,
    "sort": "position",
    "sortable": ["position", "title", "date"],
    "filterable": ["title", "teaser", "image", "category", "authors", "date", "link"],
    "links": {
      "base": "https://api.flyo.cloud/nitro/v1/blocks/collection/news-data?token=pc-1234-9f2c…",
      "self": "https://api.flyo.cloud/nitro/v1/blocks/collection/news-data?token=pc-1234-9f2c…&page=1",
      "first": "https://api.flyo.cloud/nitro/v1/blocks/collection/news-data?token=pc-1234-9f2c…&page=1",
      "prev": null,
      "next": "https://api.flyo.cloud/nitro/v1/blocks/collection/news-data?token=pc-1234-9f2c…&page=2",
      "last": "https://api.flyo.cloud/nitro/v1/blocks/collection/news-data?token=pc-1234-9f2c…&page=22"
    }
  }
}

Feld	Bedeutung
enabled	Ob die Einträge eine Collection sind. Bei false enthält items alle Einträge, und die Zähler beschreiben sie.
key	Der Schlüssel, siehe oben.
per_page	Einträge pro Seite, aus der Definition.
inline_first_page	Ob die Seite die erste Seite in items mitliefert.
total	Die Anzahl Einträge, mit einem Filter die Anzahl Treffer. Nie mehr als das Limit.
page_count, current_page	Anzahl Seiten (mindestens 1) und die Seite, die items enthält.
sort	Die Sortierung dieser Seite. position ist die Reihenfolge des Editors.
sortable, filterable	Die Felder, die sort und filter annehmen.
links	Absolute URLs auf den Collection-Endpunkt. prev ist auf der ersten Seite null, next auf der letzten. base hat weder Seite noch Sortierung noch Filter und ist der Ausgangspunkt für eigene Anfragen.

Die typisierten Schemas deiner Integration (/nitro/v1/openapi/schemas, siehe SDKs) führen sortable und filterable jedes Inhaltselements als feste Werte.

Der Collection-Endpunkt

GET /nitro/v1/blocks/collection/news-data?token=pc-1234-9f2c…&page=2

Die Antwort ist dasselbe Objekt wie das Inhaltselement in der Seite: uid, identifier, component, content, config und slots wie in der Seite, in items die verlangte Seite und in collection die Beschreibung genau dieser Seite. Dein Code kann deshalb beide gleich behandeln.

• page beginnt bei 1. Eine Seite nach der letzten liefert die letzte Seite. Prüfe beim Weiterblättern current_page gegen page_count.
• Mit dem Token der Collection brauchst du kein lang, der Token gehört bereits zu einer Sprache. Mit dem Token der Integration wählt lang die Sprache, wie bei den übrigen Endpunkten.
• Mit dem Token der Integration liefert ein unbekannter Schlüssel, oder ein Block, der keine Collection (mehr) ist, 404. Der Token einer Collection, die es nicht mehr gibt, liefert 401.

Folge am besten den Links in collection.links, statt URLs selbst zusammenzusetzen. Sie enthalten die Sortierung und den Filter der Anfrage.

Sortieren

Ohne sort behalten die Einträge die Reihenfolge des Editors. sort nimmt eines oder mehrere der Felder aus sortable an, durch Komma getrennt, mit - für absteigend:

?sort=-date
?sort=-date,title

Einträge, die sich in den verlangten Feldern nicht unterscheiden, behalten die Reihenfolge des Editors, damit die Seiten stabil bleiben. Ein Feld, das nicht in sortable steht, liefert 400.

Filtern

filter nimmt die Felder aus filterable an, in derselben Syntax wie das API SDK:

?filter[title]=Kunsthaus                        gleich
?filter[title][like]=Kunst                      enthält
?filter[date][gte]=2026-11-01                   grösser oder gleich
?filter[category:value]=kultur                  Feld eines Objekts
?filter[authors.name]=Anna Muster               Feld der Einträge einer Liste
?filter[category:value][in][]=kultur&filter[category:value][in][]=sport
?filter[or][0][title][like]=Kunst&filter[or][1][teaser][like]=Kunst

Die Operatoren sind eq, neq, lt, lte, gt, gte, in, nin und like, kombiniert wird mit and, or und not. Ein Feld eines Objekts sprichst du mit : an (category:value), ein Feld der Einträge einer Liste mit . (authors.name). Ein unbekanntes Feld oder ein unbekannter Operator liefert 400.

Keine wechselnden Werte im Filter

Jede URL ist ein eigener Cache-Eintrag. Ein Wert, der sich bei jeder Anfrage ändert, zum Beispiel die aktuelle Uhrzeit, wird nie aus dem Cache bedient, und jede dieser Anfragen geht als Serveranfrage an die Flyo-Server und verbraucht Credits. Verwende Werte, die über längere Zeit gleich bleiben, etwa das heutige Datum.

Der Token einer Collection

Die Links tragen nicht den Token der Integration, sondern den Token der Collection. Jede Collection hat einen eigenen, für jede Sprache und getrennt für die Seiten des PROD- und des DEV-Tokens. Er öffnet nur diese eine Collection, keine andere und keinen anderen Endpunkt. Dein Frontend kann den Links deshalb auch im Browser folgen, ohne den PROD-Token preiszugeben.

• Auf den Seiten des PROD-Tokens beginnt er mit pc-. Er wird wie der PROD-Token zwischengespeichert und gezählt.
• Auf den Seiten des DEV-Tokens beginnt er mit dc-. Er liefert die Vorschau und wird nie zwischengespeichert.
• Der Endpunkt nimmt auch den PROD- und den DEV-Token selbst an. Seine Links enthalten trotzdem den Token der Collection.

Flyo erstellt die Token selbst. Ein Token bleibt gleich, solange es die Collection gibt, also solange der Block mit seinem Schlüssel auf der Seite steht. Ändert sich eine Collection, löscht Flyo nur ihre Antworten im Cache. Erhält der Block einen neuen Schlüssel oder wird er entfernt, gilt der alte Token nicht mehr.

Wenn du in der Integration den PROD-Token neu generierst, erhalten alle pc- Token neue Werte. Die alten gelten sofort nicht mehr, die Seiten werden neu erstellt und ihre Antworten im Cache gelöscht. Dasselbe gilt für den DEV-Token und dc-. Siehe auch Authentifizierungs-Token.