Seiten lesen

useGinko

useGinko(baustein) liest einen Baustein. Der Rückgabewert ist ein ComputedRef. In <script> greifst du mit .value zu, im Template nicht.

• Für ein Einzelstück liefert er { data, fallback }. data enthält die Felder.
• Für eine Sammlung liefert er { items }. Jedes Element hat id, data und fallback. Ein Element eines Bausteins mit route hat dazu url, seine Adresse in der aktuellen Sprache (nutze sie für Links), und urls, seine Adresse in jeder Sprache, in die es übersetzt ist (für einen Sprachumschalter). Steht ein Eintrag mit untranslated: 'fallback' in einer Sprache ohne Übersetzung in der Liste, ist url die Seite in der Hauptsprache. updatedAt ist die Zeit der letzten Änderung (ISO 8601, UTC), wenn sie bekannt ist.

<script setup lang="ts">
import { formatMoney } from '@lupinum/ginko'

const menu = useGinko('menu')
const { language } = useI18n()
</script>

<template>
  <ul>
    <li v-for="item in menu.items" :key="item.id">
      {{ item.data.name }}: {{ formatMoney(item.data.price, language) }}
    </li>
  </ul>
</template>

useI18n() gehört zu ginko-i18n. Es liefert das Sprach-Tag der aktuellen Sprache (etwa de-AT) als language. useGinko ist automatisch importiert. formatMoney nicht: importiere es aus @lupinum/ginko.

Die Typen kommen aus deiner ginko.config.ts. item.data.price ist dort ein f.money-Feld, also ein { amount, currency }. Ein freiwilliges Feld kann undefined sein.

useGinko gibt bei einer Sammlung nur sichtbare Einträge zurück, in der Reihenfolge des Bausteins. Die Regel steht in „Bausteine“, Abschnitt „Sichtbarkeit“.

Bekommt eine Komponente einen Eintrag als Prop, nimm den Typ GinkoItem mit dem Namen des Bausteins. Er wird automatisch importiert:

<script setup lang="ts">
defineProps<{ dish: GinkoItem<'menu'> }>()
</script>

useGinkoEntry

useGinkoEntry(baustein, slug) liest einen Eintrag einer Sammlung mit route. Du gibst den Slug aus der Adresse als Funktion mit. So folgt der Eintrag der Route, wenn Nuxt die Seite für einen anderen Eintrag wiederverwendet. Die Datei liegt zum Beispiel unter app/pages/veranstaltungen/[slug].vue:

<script setup lang="ts">
definePageMeta({ i18n: { paths: { en: '/events/:slug()' } } })
const route = useRoute()
const event = useGinkoEntry('events', () => route.params.slug)
</script>

<template>
  <article>
    <h1>{{ event.data.title }}</h1>
    <GinkoMarkdown :value="event.data.description" />
  </article>
</template>

useGinkoEntry baut den Pfad aus der Route des Bausteins und dem Slug. Eine Slug-Liste (von einer Catch-all-Seite wie [...slug].vue) wird mit / verbunden. Dann sucht es den sichtbaren Eintrag, dessen Adresse in der aktuellen Sprache genau dieser Pfad ist. Findet es keinen, antwortet die Seite mit einem echten 404. Das passiert bei einem falschen oder fehlenden Slug, bei einem nicht sichtbaren Eintrag, bei einem Eintrag, der in dieser Sprache nicht übersetzt ist, und beim Slug einer anderen Sprache. Das 404 entsteht bei jedem Lesen des Eintrags (im Template oder mit .value), solange kein Eintrag passt, nicht beim Aufruf.

useGinkoQuery

useGinkoQuery(brick, query) filtert, sortiert und blättert die sichtbaren Einträge einer Sammlung. Es liest die Daten der Seite, keine Datenbank:

const hauptspeisen = useGinkoQuery('menu', { where: { category: 'mains', price: { lte: { amount: 1500 } } }, order: 'price desc, name', limit: 10 })

where nimmt pro Feld einen Wert (das Feld muss ihm gleich sein) oder eine Bedingung. Jedes Feld muss passen:

• eq, ne: gleich oder ungleich. Bei einem Listenwert (f.choices, f.refs) zählt ein Element.
• gt, gte, lt, lte: größer oder kleiner. Geld vergleicht nach amount, ein daterange nach seinem Startdatum, Datum und Uhrzeit als Text.
• in: gleich einem der Werte in der Liste.
• contains: ein Text enthält den Text (Groß- und Kleinschreibung zählen gleich), eine Liste enthält den Wert.

order ist ein Text wie 'price desc, name' (asc ist der Standard) oder { field, dir? }. limit muss mindestens 1 sein; page beginnt bei 1. fields behält nur diese Felder, facets zählt die Werte dieser Felder über alle Treffer, und include ersetzt die IDs dieser ref-Felder durch die Einträge. Die Typen kommen aus deiner Konfiguration: Ein Feld, das der Baustein nicht hat, ist ein Typfehler in deinem Code-Editor und ein Fehler, wenn die Abfrage läuft.

useGinkoToday

useGinkoToday() liefert das heutige Datum als YYYY-MM-DD, in der Zeitzone der Seite. Der Wert ist ein Ref. Auf dem Server gilt zuerst der Wert des Servers, damit Server und Browser denselben Tag rendern. Im Browser läuft der Wert nach Mitternacht weiter, direkt nach dem Laden, jede Minute und beim Zurückkehren in den Tab. useGinko filtert mit diesem Wert. Abgelaufene Hinweise verschwinden also ohne Neuladen.

Nutze useGinkoToday() auch für eigene Datumsvergleiche, zum Beispiel „heute geöffnet“.

useGinkoSite

useGinkoSite() gibt die Angaben der Seite aus ginko.config.ts zurück: name, url (die Adresse in production), locales, mainLocale (die erste Sprache) und timeZone. Nutze es für absolute Links, zum Beispiel in JSON-LD:

const { url } = useGinkoSite()
const address = new URL(useRoute().path, url).href

Das Modul schreibt weitere Werte nach runtimeConfig.public.ginko. Sie sind intern und können sich in jedem Release ändern. Lies die Seite darum nur über useGinkoSite().

GinkoMarkdown

<GinkoMarkdown :value> zeigt den Wert eines f.markdown-Feldes an:

<GinkoMarkdown :value="legal.data.imprint" class="prose" />

Der Text liegt als Markdown vor, das Bundle liefert ihn schon als Baum. Es läuft kein Parser im Browser und kein v-html. Ein unsicherer Link (zum Beispiel javascript:) wird zu reinem Text, und ein Attribut, das der Parser nicht erlaubt (zum Beispiel style), fällt weg. Mit :components ordnest du Tags eigene Komponenten zu; eine Komponente behält die Props, die components in ginko.config.ts für sie nennt. Mehr dazu unter „Inhalte aus Dateien“.

useGinkoSeo

useGinkoSeo setzt den Kopf einer Seite: Titel (mit seo.titleTemplate der Site), Beschreibung, Open-Graph- und Twitter-Tags und JSON-LD. ginko-i18n setzt den Canonical-Link und hreflang (siehe Sprachen). Ruf es einmal pro Seite auf, mit einer Funktion, damit die Werte dem Inhalt folgen:

const route = useRoute()
const event = useGinkoEntry('events', () => route.params.slug)
useGinkoSeo(() => ({
  title: event.value.data.title,
  image: event.value.data.image?.url,
  type: 'article',
}))

Vorschaukarten. Seiten aus create-ginko bringen nuxt-og-image und seinen Renderer @takumi-rs/core mit. Dann bekommt jede Seite eine erzeugte Karte für Links in Chats und sozialen Netzwerken: Name und Logo der Site (seo.organization.logo), Titel, Beschreibung, section und das image der Seite, auf der Markenfarbe seo.color. Auf einer hellen Markenfarbe ist die Schrift dunkel. Für eine bestehende Site (Nuxt 4.6.1 oder neuer) installierst du nuxt-og-image und @takumi-rs/core und trägst 'nuxt-og-image' in modules ein. Eine Site, die auf einem Server rendert, braucht NUXT_APP_SECRET (siehe Veröffentlichen). Mit dem Modul werden die Werte der Karte einmal gelesen, wenn useGinkoSeo läuft: Ruf es auf, nachdem die Daten der Seite geladen sind. Ohne das Modul ist og:image das image der Seite oder seo.image, und Ginko lädt nichts von nuxt-og-image.

formatMoney

formatMoney(money, language) macht aus einem Geldwert einen Text. language ist ein Sprach-Tag wie de-AT, nicht der Code der Sprache: Auf einer Seite übergibst du useI18n().language. Importiere sie aus @lupinum/ginko.

Alle Leerzeichen im Ergebnis sind geschützte Leerzeichen. So bricht der Preis nicht um, und Server und Browser zeigen denselben Text.

Fallback und das Attribut lang

Fehlt die Übersetzung eines Feldes in der aktuellen Sprache, zeigt das Bundle den Text der Hauptsprache. Eine veraltete Übersetzung, deren Haupttext sich danach geändert hat, bleibt, wie sie ist, bis jemand sie neu übersetzt oder bestätigt; das Studio markiert sie. In einem Baustein mit route fehlt ein Eintrag ohne übersetzten Pflichttext dagegen ganz in dieser Sprache (siehe Sprachen). Die Liste fallback nennt jedes solche Feld mit seinem Pfad. Bei einem Feld in einer Listenzeile besteht der Pfad aus Feld, Zeilen-_id und Spalte, zum Beispiel days.k3Fd9aZ0qx.dish.

Ein Screenreader liest einen fremden Text mit der falschen Aussprache, wenn die Seite ihn nicht markiert. Setze deshalb lang auf die Hauptsprache, wenn der Pfad in fallback steht.

Ginko bringt dafür useGinkoLang() mit (automatisch importiert). Es gibt eine Funktion (item, path) zurück. Die Funktion liefert den Sprach-Tag der Hauptsprache, zum Beispiel de-AT aus languages in ginko.config.ts, wenn das Feld aus dem Fallback kommt, sonst undefined:

<script setup lang="ts">
const menu = useGinko('menu')
const langOf = useGinkoLang()
</script>

<template>
  <h3 v-for="item in menu.items" :key="item.id" :lang="langOf(item, 'name')">{{ item.data.name }}</h3>
</template>

Für eine Listenzeile eines Einzelstücks nennst du den vollen Pfad:

<span :lang="langOf(lunch, `days.${day._id}.dish`)">{{ day.dish }}</span>

Bei einem Bild heißt der Pfad des Alternativtexts image.alt, wenn das Feld image heißt. Ein Wert undefined lässt das Attribut weg.

Das Attribut lang am <html>-Element setzt ginko-i18n für dich. Siehe „Sprachen“.

Fehler und Cache

Die Seite lädt das Bundle einmal pro Anfrage. Scheitert das (Netzwerk, Serverfehler, falsches Format, zu viele Anfragen), antwortet die Seite mit 503 und nie mit 404. Auf Vercel behält ein 503 die alte, gute Seite im Cache, ein 404 würde sie ersetzen. Nur ein bestätigt fehlender Eintrag liefert 404. Das Modul schaltet für alle Seiten ISR ein (standardmäßig expiration: 60, Abfrageparameter teilen sich einen Cache-Eintrag). Deine eigenen Server-Routen unter /api/** und Ginkos dynamische Routen unter /__ginko/ laufen ohne Cache (Details: Veröffentlichen). Eine Seite, deren Bausteine alle aus Dateien kommen, fragt die Plattform nie und kann deshalb keinen 503 wegen der Plattform liefern.

API-Referenz

Automatische Importe

Das Nuxt-Modul importiert diese Funktionen in jede Komponente, Seite und jedes Composable deiner Seite. brick ist der Schlüssel eines Bausteins in ginko.config.ts. Die Typen folgen aus deiner Konfiguration.

Die Regel für die Namen: Eine Funktion, die den Nuxt-Kontext braucht, beginnt mit useGinko. Rufe sie in setup oder in einem anderen Composable auf, nicht in einem Event-Handler. Eine Funktion ohne Nuxt-Kontext wird nicht automatisch importiert; du importierst sie aus @lupinum/ginko (siehe unten). Die einzige Ausnahme ist fetchGinkoMarkdown: Es braucht die eigenen Routen der Seite, aber keinen Nuxt-Kontext. Darum kannst du es überall in der Seite aufrufen.

Auch diese Typen werden automatisch importiert:

Server-Routen

Eigene Server-Routen (server/routes/, server/middleware/) bekommen einen weiteren Auto-Import:

Komponenten

@lupinum/ginko

Diese Namen importierst du selbst:

Es exportiert auch diese Typen. Jeder kommt aus deiner Konfiguration oder aus einer Funktion oben:

@lupinum/ginko/vue exportiert GinkoMarkdown für eine Vue-App ohne Nuxt. Es heißt wie die Nuxt-Komponente, hat aber einen kleineren Vertrag: value muss ein MarkdownTree (oder null) sein, weil es keine Texte nachlädt; und es nutzt nur die Komponenten, die du in components übergibst, keine, die ein Modul bereitstellt (etwa @lupinum/ginko-components). Übergib deine Komponenten-Registry (aus defineComponents) als registry: Eine Komponente behält nur die Props, die sie dort deklariert, ohne sie nur title, lang, dir und aria-*. Es rendert sofort und braucht kein <Suspense>. Das Nuxt-<GinkoMarkdown> ist asynchron, was Nuxt-Seiten von selbst abfangen.

@lupinum/ginko/search liest den Suchindex einer Seite: loadIndex, search und die Typen SearchHit, SearchIndex und SearchIndexJson. loadIndex ist asynchron: Es lädt auch die Wortregeln (Stemmer) der Sprache des Index, und nur diese. Ein Beispiel steht auf SEO und Agenten.

Diese Einstiegspunkte sind die öffentliche API. @lupinum/ginko/internal und @lupinum/ginko/internal/search sind für Ginkos eigene Pakete und können sich in jedem Release ändern.