Co patro dodává a co ne

Patro je redakční systém, který nemá vlastní web. Obsah v něm spravuje redaktor, ale vykresluje ho někdo jiný — vaše šablona. Tenhle návod je o té druhé půlce: jak vzít hotovou Astro šablonu a nechat do ní téct obsah z patra.

Kde je hranice

Držte se jedné věty a většina rozhodnutí z ní vypadne sama:

Patro dodává obsah a jeho strukturu. Šablona dodává vzhled.

Prakticky:

Patro	Šablona
Co je na webu za stránky, v jakých jazycích	Jak stránka vypadá
Typy obsahu a jejich pole (článek má perex, akce má datum)	Jak se to pole vykreslí
Navigace, přesměrování, taxonomie, autoři	Rozvržení, písma, barvy
Tělo stránky složené redaktorem z bloků	Barvy a struktura těch bloků (viz dál)
Komentáře a jejich schvalování	Jak diskuse vypadá

Patro tedy neposílá HTML, ale typovaný JSON — i formátovaný text chodí jako strom uzlů. HTML z něj vzniká teprve u vás: serializuje ho @patro/render během vykreslování stránky, nad seznamem povolených prvků. Sanitizace tedy nebydlí v patru, ale v balíku, který si spouštíte — což je dobře vědět, než na ni někdo začne spoléhat z opačné strany.

Jedna hodnota přesto značky nese a je to past, kterou rozebírá kapitola o klientovi u metody client.searchEntries: úryvek výsledku hledání má kolem shody <mark>, ale text okolo je syrový obsah od redaktora.

Dvě cesty, kterými obsah přiteče

Podle toho, co redaktor v administraci vyplňuje, se obsah dostane ven jedním ze dvou způsobů. Návod je podle toho rozdělený na dvě půlky.

Datová půlka — typovaný JSON

Seznam stránek, detail stránky, menu, taxonomie, autoři, výsledky hledání. Ptáte se klientem, dostanete objekt, vykreslíte ho po svém. Patro o vaší šabloně neví vůbec nic a vy o něm víte jen adresu a token.

---
import { env } from "cloudflare:workers"
import { createPatroClient } from "@patro/render"

const client = createPatroClient({
  baseUrl: env.PUBLIC_API_BASE,
  token: env.PATRO_TENANT_TOKEN, // secret, nikdy ne v konfiguraci
})

const entries = await client.listEntries({ locale: "cs" })
---

<ul>
  {entries.map((entry) => <li><a href={`/${entry.slug}`}>{entry.title}</a></li>)}
</ul>

Tohle je to, čemu se říká headless, a je to obsah kapitoly o klientovi.

Bloková půlka — tělo stránky z editoru

Tělo stránky si redaktor skládá z bloků (nadpis, text, obrázek, sloupce, výzva, diskuse…). Ty vykresluje patro, ne vy — dostanete hotovou komponentu, které předáte data. Je to jediné místo, kde vám do stránky vstupuje cizí značkování.

Aby to nerozbilo vzhled šablony, jsou na to dvě cesty a obě popisuje samostatná kapitola:

• Obarvit — bloky nenesou barvy, jen role (text-block-fg, bg-block-accent, …). Šablona jim ve svém :root nastaví hodnoty a je hotovo.
• Nahradit — když má šablona hero postavené strukturálně jinak, podstrčí místo našeho bloku vlastní komponentu mapou „jméno bloku → komponenta“.

Tři věci, které je lepší vědět hned

1. Šablona přibere Svelte

Bloky jsou Svelte komponenty. I čistě Astro šablona proto potřebuje integraci @astrojs/svelte a dva @source řádky v CSS, aby Tailwind viděl třídy uvnitř bloků. Platí to i pro náhradu bloku — komponenta, kterou podstrčíte, musí být taky Svelte, protože se vykresluje uprostřed Svelte SSR a Astro komponenta tam nemůže.

Není to tak zlé, jak to zní: obal kolem vlastního značkování je .svelte soubor s $props() a HTML, žádné runy nepotřebuje. Ale rozhodnutí to je a patří ho udělat dřív, než se šablona kupuje.

Jestli vaše stránka žádné tělo z editoru nepotřebuje (typy obsahu umí mít tělo vypnuté), nepotřebujete ani Svelte — pak jste čistě na datové půlce.

2. Redaktor v editoru neuvidí váš vzhled

Náhled v administraci kreslí bloky s výchozími hodnotami rolí a náhradu bloku neuvidí vůbec. Administrace obsluhuje víc webů naráz, takže podoba jednoho by ostatním lhala.

Redaktor tedy v editoru vidí strukturu a role („tohle je pruh s akcentem“), ne finální podobu. Je to daň za sdílenou administraci a je lepší ji říct redaktorovi předem, než ho nechat objevit, že web vypadá jinak než editor.

3. Obsah je živý, takže patro musí být dosažitelné

Šablona si obsah tahá za běhu, ne při buildu. Když patro neodpovídá, není čím stránku naplnit — a návod na to má hotovou odpověď (loadContent, isOutage, outageResponse), aby z toho byla čitelná stránka „web je chvíli mimo“ místo pětistovky. Ozdoba (navigace, patička, výpisové bloky) se přitom ošetřuje sama: nedostupné patro znamená stránku bez navigace, ne rozbitou stránku.

Kudy dál

1. Napojení a token — odkud se bere token a co s ním jde.
2. Klient a jeho metody — všechno, na co se dá zeptat.
3. Položky, pole a výpisy — detail stránky a seznamy.
4. Menu, přesměrování, jazyky — routování webu.