Eigene Blöcke bauen und registrieren
Einen eigenen Block für den Seiten-Editor anlegen – in der Oberfläche oder als Datei –, Typen erzeugen, die Darstellung auf der Website bauen und Container mit Slots nutzen.
Worum es geht
Reichen die eingebauten Blöcke nicht, legen Sie eigene an – etwa eine Preistabelle oder eine Kundenstimme. Ein eigener Block besteht immer aus zwei Hälften:
- Die Definition in Sites: Name, Slug, Felder, bei Containern die Slots. Sie bestimmt, was die Redaktion im Seiten-Editor ausfüllt.
- Die Darstellung auf der Website: eine Komponente im Code Ihrer Website. Sie bestimmt, wie der Block aussieht.
Fehlt die zweite Hälfte, kann die Redaktion den Block zwar einsetzen, die Website zeigt ihn aber nicht.
Voraussetzungen
- Recht Block-Definitionen verwalten für die Oberfläche; für die Kommandozeile ein Token mit Verwaltung.
- Blöcke gehören zur aktiven Umgebung.
Eingebaute Blöcke
Diese Slugs sind vergeben und lassen sich nicht überschreiben:
- Inhalt und Medien:
hero,richtext,image,gallery,cta,html - Daten:
collectionList,sammlungsliste,collectionRepeater(nur Bestand, nicht mehr in der Palette) - Container und Layout:
section,container,columns,spacer - Daten aus anderen Apps:
eventliste,ticketkauf,buchungskalender,firmenanfrage,loungebestellung,preiskategorien - Grundbausteine:
basisStapel,basisRaster,basisKarte,basisUeberschrift,basisText,basisKnopf,basisLink,basisSymbol,basisKennzeichen,basisListe,basisKennzahl,basisAufklapper,basisTrennlinie,basisFormularsowie die fünf mit ZustandbasisReiter,basisReiterSeite,basisUmschalter,basisWechseltext,basisDialog(auch in der Hike-Umgebung, dort ohne Formular-Versand) - Rahmen-Bausteine, nur in Layouts:
rahmenLogo,rahmenMenue,rahmenSprachwahlundrahmenInhalt, der Inhaltsbereich: Dort setzt jede Seite ihre eigenen Blöcke ein. Ein Layout hat genau einen Inhaltsbereich, in Seiten und Seitenvorlagen gibt es ihn nicht. - Nur in der Hike-Umgebung (zusätzlich zu allem oben):
hikeHero,hikeZahlen,hikeAnlaesse,hikeSchritte,hikeProjekte,hikeSponsoren,hikeKopf,hikeFuss
Die Liste unter Blöcke zeigt nur Ihre eigenen Blöcke. Was die eingebauten Blöcke leisten, steht in Seiten mit Blöcken gestalten.
Die Palette im Seiten-Editor
Die Block-Palette im Seiten-Editor gruppiert die Blöcke nach Zweck, nicht nach der groben Kategorie: Grundbausteine, Kopfzeile und Navigation, Einstieg, Inhalt, Merkmale, Stimmen, Kennzahlen, Preise, Häufige Fragen, Aufruf, Medien, Interaktiv, Formulare, Shop, Buchung, Ticketing, Gastro, Blog, Rechtliches, Fusszeile und Erweitert. Eigene Blöcke, die nicht aus der Bibliothek stammen, stehen in der Gruppe Eigene Blöcke. Gruppen lassen sich auf- und zuklappen, und die Suche findet Blöcke auch über Stichwörter.
In jeder Umgebung steht die ganze Bibliothek bereit: alle Code-Blöcke, Grundbausteine und Komponenten von Scorebase, auch wenn die Umgebung neu ist und nichts davon angelegt hat. Wählen Sie einen Baustein, der in der Umgebung noch fehlt, legt Scorebase ihn beim Einsetzen an, und die Zeile zeigt kurz, dass sie arbeitet. Ihre eigenen Blöcke stehen daneben. Bestehende Seiten ändern sich dadurch nicht.
Ein Auge an einem Baustein bedeutet: Ihre Website zeichnet diesen Baustein nicht. Sie können ihn einsetzen, aber auf der Website erscheint er erst, wenn Ihr Entwickler die Darstellung ergänzt.
Was die Palette zeigt, hängt weiter von Abo und Rolle ab:
- Blöcke nicht abonnierter Apps fehlen, auch die eingebauten Daten-Blöcke (
eventliste,ticketkauf,preiskategorien,buchungskalender,firmenanfrage,loungebestellung). Shop-Blöcke brauchen das Abo der E-Commerce-App, Buchungs-Blöcke das der Termine-App, Ticketing-Blöcke das Eventmanager-Abo, Bestell-Blöcke das Gastro-Abo. Was schon auf einer Seite steht, bleibt stehen und bearbeitbar; nur das neue Einsetzen entfällt. - Bei geschlossener Kasse fehlen die Verkaufs-Bausteine. Ist das Abo einer Verkaufs-App abgelaufen und die Kasse geschlossen, bietet die Palette deren Bausteine nicht zum neuen Einsetzen an.
- Der Block
htmlist nur für Organisations-Admins. Er steht bei allen anderen nicht in der Palette, und der Server lehnt Speichern mit neuem oder geändertemhtmlab: „Den Block „html“ dürfen nur Organisations-Admins einsetzen oder ändern. Bitten Sie eine Admin-Person, die Seite zu speichern.“ Ein unveränderterhtml-Block lässt sich weiter speichern. Die Sperre gilt überall, wo einhtml-Block entstehen kann: auch in Komponenten, beim Zurückholen oder erneuten Veröffentlichen einer früheren Version und in der Live-Vorschau. Admin heisst die Rolle Organisations-Admin, oder eine Support-Freigabe mit dieser Rolle. Über die Management-API undhcms pushmuss die Person Admin sein, die das Token erstellt hat; ein Token ohne Ersteller darf kein HTML einsetzen.
Grenze: Die Regel gilt dem Slug
html. Ein eigener Block, der selbst rohes HTML zeichnet, wird vom CMS nicht erkannt.
In der Palette: Eigene Blöcke
Ein Block, der weder eingebaut ist noch aus der Bausteinbibliothek stammt, steht im Seiten-Editor in der Gruppe Eigene Blöcke. Die Gruppe trägt das Kennzeichen Eigener Code: Die Darstellung kommt aus dem Code Ihrer Website. Das gilt auch für Blöcke, die Sie in der Oberfläche angelegt haben.
Schnellweg: hcms block neu
Für einen Block mit eigener Logik, etwa mit Daten von einer fremden Schnittstelle, legen Sie Komponente und Definition in einem Schritt an. Der Befehl braucht weder Netz noch Token:
hcms block neu wartezeit-anzeige --felder titel:text,hinweis:text,schwelle_rot:number
hcms blocks pushEr schreibt components/blocks/wartezeit-anzeige.tsx und cms/blocks/wartezeit-anzeige.json und trägt den Block in registry.tsx ein. Ohne --felder entsteht ein Feld titel. Liegt der Code schon im Projekt, leitet der Befehl die Eigenschaften daraus ab und verändert den Code nie. Feldschlüssel müssen in snake_case stehen (schwelle_rot, nicht schwelleRot). Der Push überträgt nur die Beschreibung der Eigenschaften: Der Code läuft nie auf dem Server, jede Website braucht die Komponente in ihrem Projekt. Wie der Block danach in weitere Umgebungen kommt, steht in Eigene Blöcke im Register der Organisation.
Einen Block in der Oberfläche anlegen
- Öffnen Sie Blöcke und klicken Sie auf Block erstellen.
- Unter Stammdaten:
- Name, z.B. „Preis-Tabelle“,
- Slug, z.B.
preis-tabelle(Kleinbuchstaben, Ziffern und Bindestriche), - Beschreibung,
- Kategorie (Layout, Inhalt, Medien, Daten, Einbettung, Benutzerdefiniert) – bestimmt, wo der Block in der Auswahl erscheint,
- Icon (lucide-Name), z.B.
Table.
- Unter Felder legen Sie die Felder an – mit denselben Feldtypen wie bei Collections (siehe Collections und Felder).
- Soll der Block andere Blöcke aufnehmen, schalten Sie unter Slots Nimmt Kind-Blöcke auf (Container) ein und legen mit Slot die Bereiche an, z.B. „Inhalt“.
- Klicken Sie auf Speichern.
Die Liste zeigt je Block Name, Slug, Kategorie, Quelle (CMS, CLI, Marketplace oder Code), die Zahl der Felder und Aktualisiert. Löschen entfernt einen Block; Seiten und Layouts, die ihn verwenden, zeigen ihn danach als unbekannt an.
Einen Block als Datei anlegen
{
"$format": "hcms/block@1",
"slug": "preis-tabelle",
"name": "Preis-Tabelle",
"category": "content",
"icon": "Table",
"version": 1,
"allowsChildren": false,
"slots": [],
"fields": [
{ "key": "title", "label": "Titel", "type": "text", "required": true },
{ "key": "plans", "label": "Pläne", "type": "json" }
]
}Speichern Sie die Datei als cms/blocks/preis-tabelle.json und übernehmen Sie sie:
hcms blocks push --dry-run
hcms blocks push- Einfacher Block:
"allowsChildren": false,"slots": []. - Container:
"allowsChildren": trueund Slots, z.B.[{ "key": "content", "label": "Inhalt" }]. - Stil: Mit
"styleProps", z.B.["background", "paddingTop", "paddingBottom"], erklärt der Block, welche Stil-Eigenschaften er annimmt (ohne Angabe keine); die Content API liefert den Stil dann je Gerät unterstyleam Block, und die Vorlagen setzen ihn mitblockStylePropsaus dem SDK als CSS-Variablen--hcms-*um.
Eigene Code-Blöcke mit Stil
Ein Block aus Code bekommt seinen Stil als Eigenschaft hcmsStyle. Das Gerüst, das hcms types generate --scaffold-blocks anlegt, enthält sie schon: Sie geben hcmsStyle am äussersten Element weiter (<section {...props.hcmsStyle}>), den Rest erledigt die Vorlage. Der Inspektor in Scorebase zeigt am Block genau die Stil-Eigenschaften aus styleProps, nicht mehr und nicht weniger. hcms types generate schreibt dafür zusätzlich block.schema.json neben die Typen; Ihr Editor schlägt damit in der Block-Datei Schlüssel vor und prüft sie.
Stil-Werte verweisen meist auf Werte des Themes, z.B. {colors.primary}. Ein Verweis auf einen Wert, der erst im Entwurf des Themes steht, gilt beim Speichern als bekannt. Veröffentlichen Sie die Seite oder das Layout, bevor das Theme veröffentlicht ist, weist Scorebase darauf hin: Die Website kennt den Wert dann noch nicht und zeigt dort ihre Vorgabe (den Ersatzwert der CSS-Variable). Ein Verweis auf eine Stil-Eigenschaft, die der Block nicht in styleProps erklärt, wird beim Veröffentlichen entfernt. Details: Theme.
hcms blocks pull holt in der Oberfläche angelegte Blöcke als Dateien ins Projekt.
Die Darstellung auf der Website bauen
1. Typen und Gerüst erzeugen:
hcms types generate --scaffold-blocksDer Befehl erneuert cms/types.generated.ts und legt für jeden Block ohne Komponente eine Vorlage components/blocks/<slug>.tsx an. Bestehende Dateien werden nie überschrieben.
2. Komponente eintragen in components/blocks/registry.tsx:
import { PreisTabelle } from "./preis-tabelle"
const BLOCKS: Record<string, ComponentType<Record<string, unknown>>> = {
// …
"preis-tabelle": PreisTabelle,
}Ohne diesen Eintrag wird der Block beim Darstellen übersprungen. Mit renderBlocks(blocks, { fallback: "generic" }) zeigen die Vorlagen unbekannte Blöcke stattdessen Feld für Feld an – hilfreich während der Entwicklung.
3. Komponente ausbauen. Die Felder kommen als Props an, typisiert über cms/types.generated.ts.
In der Vorschau anklickbar machen
Im Vorschaufenster wählt ein Klick (Modus Bearbeiten) eine Stelle, und der Editor springt zum passenden Feld. Dafür markiert Ihre Komponente die Elemente, die ein Feld zeigen. Der Frontend-Starter bringt dafür Helfer in components/vorschau/marken.ts mit:
import { aktion, bildFeld, textFeld } from "@/components/vorschau/marken"
<h2 {...textFeld("title")}>{title}</h2> // Text, der genau dem Feldwert entspricht
<img {...bildFeld("image")} src={src} alt={alt} />
<li {...textFeld(["plans", i, "name"])}>{plan.name}</li> // Wiederholgruppe mit Zeilennummer
<form {...aktion("senden")}>…</form> // sendet in der Vorschau nie abDie Markierungen tragen nur Feldnamen, nie Werte, und ändern weder Klassen noch Aufbau. Ausserhalb einer Vorlage baut hcmsMarkierung aus @kailua-packages/headless-sdk/vorschau-markierung dieselben Attribute. Die Hülle um den ganzen Block setzt nicht die Komponente, sondern die Vorlage in components/blocks/registry.tsx, nur im Entwurfsmodus. Die Regeln für Ihren Code stehen in der Datei CLAUDE.md der Vorlage (Abschnitt „Preview contract“) und in der Integrationsanleitung (Kapitel 8, „Markierungen und Block-Hülle“).
Rahmen-Bausteine
Rahmen-Bausteine gehören nur in Layouts. Es gibt vier: rahmenLogo (Bild oder Name, verlinkt zur Startseite), rahmenMenue (aus Menüs), rahmenSprachwahl (die Sprachen der Umgebung) und rahmenInhalt, der Inhaltsbereich.
- Ein Layout enthält nur Gerüst und Rahmen und genau einen Inhaltsbereich. An dessen Stelle setzt jede Seite ihre eigenen Blöcke ein; in Seiten und Seitenvorlagen gibt es den Inhaltsbereich nicht.
- Kopfzeile und Fusszeile gibt es als Vorbelegung: Im Layout-Builder fügen Sie sie aus fertigen Bausteinen ein (Kopfzeile: Logo, Menü und Sprachwahl; Fusszeile: Logo und Fussmenü) und bauen sie danach nach Belieben um. Den Inhaltsbereich bringen die Vorbelegungen nicht mit; er steht im Layout schon.
- Das Menü bindet sich über den Schlüssel (
key) des Menüs. Ein Menü, das ein Layout verwendet, lässt sich deshalb nicht umbenennen.
Was Ihre Website tun muss: Für diese Bausteine braucht sie eine Darstellung wie für jeden anderen Block, und sie muss die Seite in den Rahmen setzen. Der Frontend-Starter trägt beides in components/blocks/registry.tsx ein. Bei einer eigenen Website liefert @kailua-packages/headless-sdk/rahmen die Helfer: teileRahmen trennt den Rahmen vom Seitenbaum, setzeSeiteInRahmen setzt die Seite an die Stelle des Inhaltsbereichs, und leseRahmenMenue bzw. leseRahmenSprachen lesen Menü und Sprachen aus dem aufgelösten Block. Die vier Typen tragen Sie in der Registry ein (rahmenLogo, rahmenMenue, rahmenSprachwahl, rahmenInhalt). Mehr zum Aufbau von Rahmen steht unter Layouts und der Layout-Builder.
Ausgeblendete Blöcke
Jeder Block kann in der Redaktion ausgeblendet werden (siehe Seiten mit Blöcken gestalten). In der Blockform steht dafür das Merkmal hidden. Die Content API liefert ausgeblendete Blöcke samt ihren Unterblöcken nie aus; Ihre Website muss nichts dafür tun. Die Management-API (hcms pull und hcms push) behält hidden bei.
Eingesetzte Komponenten
Websites sehen eingesetzte Komponenten nie als eigene Blöcke: Die Content API liefert an ihrer Stelle die Bausteine der Komponente, mit den Werten der Stelle. Einen Block componentInstance braucht Ihre Website deshalb nicht darzustellen. Mehr dazu unter Komponenten im Builder und im Code.
Block-Werkzeug im Vorschaufenster
Im Modus Bearbeiten des Vorschaufensters trägt der gewählte Block eine Leiste: Nach oben, Nach unten, Duplizieren, Ausblenden, Entfernen, Felder im Editor und darunter Block danach einfügen. Damit die Auswahl nur Bausteine anbietet, die Ihre Website auch zeichnet, meldet der Frontend-Starter seine registrierten Typen an das Fenster; bei einer eigenen Website geschieht das über das Vorschau-Modul des SDK (@kailua-packages/headless-sdk/vorschau-bloecke). Das Fenster ändert nie selbst etwas; jeder Klick geht als Befehl an den Editor. Einzelheiten stehen unter Blöcke in der Vorschau ordnen.
Container und Slots
Container-Blöcke erhalten zusätzlich zu ihren Feldern die Prop slots mit den bereits dargestellten Kind-Blöcken je Slot:
sectionundcontainer:slots.contentcolumns:slots["col-1"]bisslots["col-N"]– N ergibt sich aus dem Feldratio(1-2= zwei Spalten,1-1-1= drei)- eigene Container: je Slot-Key
export function Section(props: { slots: Record<string, ReactNode> }) {
return <section>{props.slots.content}</section>
}Einfache Blöcke erhalten nie slots. Container lassen sich höchstens sechs Ebenen tief verschachteln.
So kommt ein Block bei der Website an
Die Content API liefert eine Seite unter GET /pages/by-path?path=/… mit einem Block-Baum:
{
"id": "b1",
"type": "preis-tabelle",
"data": { "title": "Unsere Pakete", "plans": [] },
"children": { "content": [] }
}type ist der Slug, data enthält die Feldwerte, children (nur bei Containern) die Kind-Blöcke je Slot. Blöcke mit Verweisen auf Einträge (Feldtypen Collection, Eintrag, Abfrage sowie collectionList) liefert die Content API zusätzlich aufgelöst unter resolved mit. Alle verfügbaren Blöcke samt Feldern liefert GET /blocks.
Wenn etwas nicht klappt
| Symptom | Ursache | Lösung |
|---|---|---|
| Der Block erscheint nicht auf der Website | Keine Komponente oder kein Eintrag in registry.tsx |
Komponente anlegen und eintragen |
hcms blocks push meldet 422 |
Der Slug gehört einem eingebauten Block, oder ein Feldtyp ist ungültig | Anderen Slug wählen; Feldtypen prüfen. Dateien für eingebaute Slugs (section, container, richtext …) lässt push aus |
| Ein Block fehlt in der Palette | Die App des Blocks ist nicht abonniert, oder es ist html und Sie sind kein Admin |
Abo prüfen bzw. eine Admin-Person bitten. Blöcke der Bibliothek müssen Sie nicht nachrüsten: Sie stehen in der Palette bereit und werden beim Einsetzen angelegt |
Speichern meldet, html dürfe nur ein Admin einsetzen |
Die Seite enthält einen neuen oder geänderten html-Block |
Eine Admin-Person speichern lassen oder den Block entfernen |
| Der Block fehlt in der Auswahl des Seiten-Editors | Er liegt in einer anderen Umgebung | Umgebung prüfen oder Block dort anlegen bzw. übertragen |
| Neue Felder fehlen in den Typen | Typen nicht neu erzeugt | hcms types generate ausführen |