Eine Blockbibliothek erstellen
Eine Blockbibliothek ist eine Sammlung eigenständiger Abschnittsblöcke, aus denen sich vollständige Seiten zusammensetzen. Jeder Block enthält sein eigenes Schema, Template und Styling. Blockstudio stellt das Framework bereit: Tailwind CSS-Verarbeitung, Attributregistrierung und Seitensynchronisierung. Die Blöcke erstellst du selbst.
Diese Anleitung führt dich Schritt für Schritt durch den Aufbau einer Bibliothek und folgt dabei derselben Architektur wie Hunderte produktiv eingesetzter Themes. Am Ende hast du ein funktionierendes Theme mit Hero, Feature-Raster und einer vollständig gestalteten Startseite.
Ordnerstruktur
Jedes Blockstudio-Theme hat denselben Aufbau:
my-theme/
├── style.css # WordPress header + Tailwind v4 config
├── blockstudio.json # Blockstudio settings
├── functions.php # Section helper + Tailwind filter
├── index.php # Main WordPress template
├── blockstudio/
│ ├── fields/
│ │ └── section/
│ │ └── field.json # Shared section controls
│ └── sections/
│ ├── hero/
│ │ ├── block.json
│ │ └── index.php
│ └── features/
│ ├── block.json
│ └── index.php
└── pages/
└── home/
├── page.json
└── index.php
Blöcke liegen in blockstudio/sections/. Jeder Block ist ein Ordner mit einem block.json-Schema und einem index.php-Template. Seiten liegen in pages/ und setzen Blöcke mit der <block>-Syntax zusammen.
Grundlegende Dateien
blockstudio.json
Diese Datei legt fest, wie Blockstudio dein Theme verarbeitet. Die Konfiguration ist für jedes Theme gleich:
{
"assets": {
"enqueue": true,
"reset": {
"enabled": true,
"fullWidth": ["page"]
},
"minify": { "css": true, "js": true },
"process": { "scss": false, "scssFiles": true }
},
"tailwind": {
"enabled": true,
"config": ""
},
"dev": {
"canvas": { "enabled": true }
},
"$schema": "https://blockstudio.dev/schema/blockstudio"
}
reset entfernt die standardmäßigen WordPress-Blockstile. fullWidth sorgt dafür, dass sich page-Beitragstypen über die volle Breite erstrecken. canvas aktiviert den Canvas-Modus des Editors für ein übersichtlicheres Bearbeiten.
Das Feld tailwind.config ist absichtlich leer. Mit Tailwind v4 befindet sich die gesamte Konfiguration in style.css und folgt dem Ansatz CSS-first.
index.php
Das Haupt-WordPress-Template. Es ist normales WordPress und nicht speziell auf Blockstudio zugeschnitten:
<!DOCTYPE html>
<html <?php language_attributes(); ?>>
<head>
<meta charset="<?php bloginfo( 'charset' ); ?>">
<meta name="viewport" content="width=device-width, initial-scale=1">
<?php wp_head(); ?>
</head>
<body <?php body_class(); ?>>
<?php wp_body_open(); ?>
<main>
<?php
if ( have_posts() ) {
while ( have_posts() ) {
the_post();
the_content();
}
}
?>
</main>
<?php wp_footer(); ?>
</body>
</html>
Füge ein header.php und ein footer.php hinzu, wenn du Navigation brauchst. Für den Anfang reicht ein minimales Template, um Blöcke darzustellen.
Design-Tokens
Das gesamte Theming findet in style.css mit der @theme-Direktive von Tailwind v4 statt. Hier liegt das Herzstück deines Designs.
/*
Theme Name: My Theme
Theme URI: https://example.com
Description: A clean theme built with Blockstudio.
Version: 1.0.0
Requires at least: 6.0
Requires PHP: 8.2
Author: Your Name
Text Domain: my-theme
*/
@theme {
--font-sans: 'Inter', ui-sans-serif, system-ui, sans-serif;
--color-bg: #050505;
--color-elevated: #111111;
--color-subtle: rgb(255 255 255 / 0.06);
--color-muted: #888888;
--color-accent: #6366f1;
--color-accent-hover: #4f46e5;
}
Jedes Theme benötigt mindestens:
| Token | Zweck |
|---|---|
--font-sans oder --font-serif |
Primäre Schriftart |
--color-bg |
Seitenhintergrund |
--color-elevated |
Karten-/Oberflächenhintergrund |
--color-subtle |
Rahmen, Trennlinien |
--color-muted |
Sekundärtext |
--color-accent |
Primäre Markenfarbe |
Diese Tokens erzeugen automatisch Tailwind-Hilfsklassen. Aus --color-accent wird beispielsweise bg-accent, text-accent, border-accent und so weiter.
Für ein helles Theme kehrst du die Werte um:
@theme {
--font-serif: 'Zilla Slab', serif;
--font-sans: 'DM Sans', sans-serif;
--color-bg: #f5f0e8;
--color-elevated: #ece6da;
--color-heading: #2c1810;
--color-body: #6b5c4f;
--color-muted: #9a8b7d;
--color-accent: #2d5016;
--color-subtle: #d9d1c4;
}
Basisstile und Hilfsklassen
Füge unterhalb des @theme-Blocks die Body-Stile, Standardwerte der Basisebene und eigene Hilfsklassen hinzu.
Body-Stile müssen außerhalb von @layer stehen, damit der WordPress-Editor sie übernimmt:
body {
@apply bg-bg font-sans text-white antialiased;
}
Basisebene für Standardwerte von Elementen:
@layer base {
section {
@apply relative overflow-hidden;
}
h1, h2, h3 {
text-wrap: balance;
}
p {
text-wrap: pretty;
}
}
Eigene Hilfsklassen für wiederverwendbare Muster. Jedes Theme definiert eine container-Hilfsklasse für einheitliche Abschnittsabstände und üblicherweise auch card, badge und Hilfsklassen für Buttons:
@utility container-px {
@apply mx-auto max-w-5xl px-6;
}
@utility container {
@apply container-px py-24 sm:py-32;
}
@utility container-no-pb {
@apply pb-0 sm:pb-0;
}
@utility card {
@apply rounded-2xl border border-subtle bg-elevated/80 p-8 transition-all duration-300;
&:hover {
border-color: rgb(255 255 255 / 0.1);
}
}
@utility badge {
@apply inline-flex items-center gap-2 rounded-full border border-subtle bg-white/5 px-3.5 py-1.5 text-sm text-muted;
}
@utility btn-primary {
@apply inline-flex items-center gap-2 rounded-full bg-accent px-6 py-3 text-sm font-medium text-white transition-colors;
&:hover {
@apply bg-accent-hover;
}
}
@utility btn-secondary {
@apply inline-flex items-center gap-2 rounded-full border border-subtle px-6 py-3 text-sm font-medium text-white transition-all;
&:hover {
border-color: rgb(255 255 255 / 0.15);
background: rgb(255 255 255 / 0.04);
}
}
Pseudo-Selektoren gehören innerhalb des @utility-Blocks in die CSS-Verschachtelung (&:hover). Verwende sie niemals im Namen der Hilfsklasse. @utility btn-primary:hover {} ist ungültig und wird von Tailwind zurückgewiesen.
@source inline
Blockstudio durchsucht deine Block-Templates automatisch nach Tailwind-Klassen. Klassen, die außerhalb von Block-Templates verwendet werden (in functions.php, header.php, index.php), werden jedoch nicht erfasst. Deklariere sie mit @source inline:
@source inline("bg-bg bg-accent-tint container container-px container-no-pb");
So weist du Tailwind an, diese Klassen in die Ausgabe aufzunehmen, obwohl sie nur in PHP-Dateien vorkommen, die nicht durchsucht werden.
Das Abschnittsmuster
Das Abschnittsmuster ist die wichtigste Konvention in einer Blockstudio-Blockbibliothek. Mit zwei gemeinsamen Mechanismen – einem eigenen Feld und einem PHP-Helper – erhalten alle Blöcke einheitliche Abstände, einen umschaltbaren Hintergrund und eine Steuerung der Innenabstände.
Das Abschnittsfeld
Erstelle eine gemeinsame Felddefinition, auf die alle Blöcke verweisen können:
{
"$schema": "https://blockstudio.dev/schema/field",
"name": "section",
"title": "Section",
"attributes": [
{
"type": "group",
"attributes": [
{
"id": "removeBottomPadding",
"type": "toggle",
"label": "Remove bottom padding"
},
{
"id": "accentBg",
"type": "toggle",
"label": "Accent background"
}
]
}
]
}
Dieses Feld erscheint im Inspektor jedes Blocks unter dem Tab „Abschnitt“. Es bietet zwei Optionen: einen Akzenthintergrund ein- oder ausschalten und den unteren Innenabstand entfernen (praktisch, wenn du Abschnitte ohne Lücke stapeln möchtest).
Der Abschnitts-Helper
Erstelle in functions.php einen Helper, der diese Attribute in CSS-Klassen umwandelt:
<?php
/**
* My Theme functions.
*
* @package My_Theme
*/
/**
* Returns section and container class strings based on block attributes.
*
* @param array $a Block attributes.
* @param string $extra_section Additional classes for the section element.
* @param string $extra_container Additional classes for the container element.
* @return array Array of [ section_classes, container_classes ].
*/
function mytheme_section_classes( array $a, string $extra_section = '', string $extra_container = '' ): array {
$section = ! empty( $a['accentBg'] ) ? 'bg-accent-tint' : 'bg-bg';
$container = 'container';
if ( ! empty( $a['removeBottomPadding'] ) ) {
$container .= ' container-no-pb';
}
if ( $extra_section ) {
$section .= ' ' . $extra_section;
}
if ( $extra_container ) {
$container .= ' ' . $extra_container;
}
return array( $section, $container );
}
Jedes Block-Template ruft diesen Helper in seiner ersten Zeile auf. Der Helper gibt zwei Klassenlisten zurück: eine für das äußere <section>-Element und eine für den inneren <div>-Container.
Tailwind-Konfigurationsfilter
Füge ebenfalls in functions.php den Filter hinzu, der dein style.css an den Tailwind-Prozessor von Blockstudio übergibt:
add_filter(
'blockstudio/settings/tailwind/config',
function () {
$style = get_stylesheet_directory() . '/style.css';
if ( file_exists( $style ) ) {
// phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents -- Reading local theme file.
return file_get_contents( $style );
}
return '';
}
);
Damit weist du Blockstudio an, dein style.css als Konfigurationsquelle für Tailwind v4 zu verwenden. Ohne diesen Filter wären deine @theme-Tokens und @utility-Definitionen in den Block-Templates nicht verfügbar.
Dein erster Block: Hero
Ein Hero-Abschnitt veranschaulicht das vollständige Blockmuster. Beginne mit dem Schema:
{
"$schema": "https://blockstudio.dev/schema/block",
"name": "my-theme/hero",
"title": "Hero",
"category": "my-theme",
"icon": "star-filled",
"description": "Full-width hero section with heading, description, and buttons.",
"blockstudio": {
"attributes": [
{
"type": "tabs",
"tabs": [
{
"title": "Content",
"attributes": [
{
"type": "group",
"attributes": [
{
"id": "heading",
"type": "text",
"label": "Heading",
"default": "Build beautiful websites without the complexity"
},
{
"id": "description",
"type": "textarea",
"label": "Description",
"default": "A powerful framework that lets you create stunning designs using the WordPress editor."
}
]
},
{
"type": "group",
"attributes": [
{
"id": "primaryButton",
"type": "link",
"label": "Primary Button",
"default": {
"title": "Get Started",
"url": "#"
}
},
{
"id": "secondaryButton",
"type": "link",
"label": "Secondary Button",
"default": {
"title": "Learn More",
"url": "#"
}
}
]
}
]
},
{
"title": "Section",
"attributes": [
{ "type": "custom/section" }
]
}
]
}
]
}
}
Wichtige Muster:
Der Wrapper tabs erstellt einen Inspektor mit zwei Tabs: „Inhalt“ für die Felder des Blocks und „Abschnitt“ für die gemeinsamen Abschnittsoptionen. Alle Blöcke verwenden diesen Aufbau.
Felder sind in group-Containern angeordnet. Gruppen trennen zusammengehörige Felder im Inspektor optisch. Die erste Gruppe enthält Textfelder, die zweite Linkfelder.
Standardwerte liefern aussagekräftige Inhalte, damit der Block direkt nach dem Einfügen vollständig aussieht. Das ist für die Seitengestaltung entscheidend, denn Blöcke werden ohne Eingaben hinzugefügt.
Jetzt das Template:
<?php list( $section_classes, $container_classes ) = mytheme_section_classes( $a, '', 'text-center' ); ?>
<section useBlockProps class="<?php echo esc_attr( $section_classes ); ?>">
<div class="<?php echo esc_attr( $container_classes ); ?>">
<h1 class="text-5xl font-medium tracking-tight sm:text-6xl lg:text-7xl">
<?php echo esc_html( $a['heading'] ); ?>
</h1>
<?php if ( ! empty( $a['description'] ) ) : ?>
<p class="mt-6 text-lg leading-relaxed text-muted max-w-xl mx-auto">
<?php echo esc_html( $a['description'] ); ?>
</p>
<?php endif; ?>
<div class="mt-10 flex items-center justify-center gap-x-4">
<?php if ( ! empty( $a['primaryButton']['url'] ) ) : ?>
<a href="<?php echo esc_url( $a['primaryButton']['url'] ); ?>" class="btn-primary">
<?php echo esc_html( $a['primaryButton']['title'] ); ?>
</a>
<?php endif; ?>
<?php if ( ! empty( $a['secondaryButton']['url'] ) ) : ?>
<a href="<?php echo esc_url( $a['secondaryButton']['url'] ); ?>" class="btn-secondary">
<?php echo esc_html( $a['secondaryButton']['title'] ); ?>
</a>
<?php endif; ?>
</div>
</div>
</section>
Das Template folgt einem einheitlichen Muster:
- Rufe den Abschnitts-Helper auf, um CSS-Klassen zu erhalten
- Äußeres
<section>mituseBlockPropsund Abschnittsklassen - Inneres
<div>mit Containerklassen - Inhalt aus
$aausgeben (Kurzschreibweise für Attribute) - Optionale Felder bedingt ausgeben
- Korrekt maskieren:
esc_html()für Text,esc_url()für URLs,esc_attr()für Attribute
Repeater hinzufügen: Feature-Raster
Mit Repeatern können Kunden Einträge hinzufügen, entfernen und neu anordnen. Ein Feature-Raster ist das klassische Beispiel:
{
"$schema": "https://blockstudio.dev/schema/block",
"name": "my-theme/features",
"title": "Features",
"category": "my-theme",
"icon": "grid-view",
"description": "Feature grid with titles and descriptions.",
"blockstudio": {
"attributes": [
{
"type": "tabs",
"tabs": [
{
"title": "Content",
"attributes": [
{
"type": "group",
"attributes": [
{
"id": "heading",
"type": "text",
"label": "Heading",
"default": "Everything you need"
},
{
"id": "description",
"type": "textarea",
"label": "Description",
"default": "Our toolkit gives you the building blocks to go from idea to production."
}
]
},
{
"type": "group",
"attributes": [
{
"id": "features",
"type": "repeater",
"label": "Features",
"textMinimized": {
"id": "title",
"fallback": "Feature"
},
"default": [
{
"title": "Lightning Fast",
"description": "Optimized for performance with minimal overhead."
},
{
"title": "Fully Responsive",
"description": "Every component adapts across all screen sizes."
},
{
"title": "Easy to Customize",
"description": "Adjust every detail to match your brand."
}
],
"attributes": [
{
"id": "title",
"type": "text",
"label": "Title"
},
{
"id": "description",
"type": "textarea",
"label": "Description"
}
]
}
]
}
]
},
{
"title": "Section",
"attributes": [
{ "type": "custom/section" }
]
}
]
}
]
}
}
Die Eigenschaft textMinimized bestimmt, welcher Text bei eingeklappter Repeater-Zeile angezeigt wird. Sie liest den Feldwert title und verwendet „Feature“, wenn dieser leer ist. So bleibt der Inspektor auch bei vielen Einträgen übersichtlich.
Das Array default enthält die anfänglichen Einträge. Sie erscheinen, wenn der Block zum ersten Mal eingefügt wird. Verwende immer realistische Standardwerte, damit der Block sofort vollständig aussieht.
<?php list( $section_classes, $container_classes ) = mytheme_section_classes( $a ); ?>
<section useBlockProps class="<?php echo esc_attr( $section_classes ); ?>">
<div class="<?php echo esc_attr( $container_classes ); ?>">
<?php if ( ! empty( $a['heading'] ) ) : ?>
<div class="text-center max-w-2xl mx-auto">
<h2 class="text-3xl font-medium tracking-tight sm:text-4xl">
<?php echo esc_html( $a['heading'] ); ?>
</h2>
<?php if ( ! empty( $a['description'] ) ) : ?>
<p class="mt-4 text-base leading-relaxed text-muted">
<?php echo esc_html( $a['description'] ); ?>
</p>
<?php endif; ?>
</div>
<?php endif; ?>
<?php if ( ! empty( $a['features'] ) ) : ?>
<div class="mt-16 grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
<?php foreach ( $a['features'] as $feature ) : ?>
<div class="card">
<h3 class="text-sm font-medium">
<?php echo esc_html( $feature['title'] ); ?>
</h3>
<p class="mt-2 text-sm leading-relaxed text-muted">
<?php echo esc_html( $feature['description'] ); ?>
</p>
</div>
<?php endforeach; ?>
</div>
<?php endif; ?>
</div>
</section>
Auf Repeater-Einträge greifst du wie auf ein einfaches PHP-Array zu. Durchlaufe es mit foreach und rufe die Felder jedes Eintrags über dessen id ab.
Bilder und Platzhalter
Verwende für Blöcke mit Bildern den Feldtyp files und die Komponente MediaPlaceholder. Der Platzhalter zeigt im Editor eine Drag-and-drop-Zone:
{
"id": "image",
"type": "files",
"label": "Image"
}
Gib das Bild im Template mit wp_get_attachment_image() aus und zeige ein SVG als Platzhalter an, wenn kein Bild ausgewählt ist:
<div class="overflow-hidden rounded-2xl bg-elevated">
<MediaPlaceholder attribute="image" allowedTypes="<?php echo esc_attr( wp_json_encode( array( 'image' ) ) ); ?>" />
<?php if ( ! empty( $a['image'] ) ) : ?>
<?php echo wp_get_attachment_image( $a['image'][0]['ID'], 'full', false, array( 'class' => 'block w-full' ) ); ?>
<?php else : ?>
<?php echo blockstudio_placeholder_dark(); ?>
<?php endif; ?>
</div>
blockstudio_placeholder_dark() gibt ein Inline-SVG zurück, das currentColor mit der Variablen --color-accent verwendet und sich dadurch automatisch an dein Theme anpasst. Für helle Themes verwendest du blockstudio_placeholder_light(). Beide akzeptieren ein Variantenargument:
blockstudio_placeholder_dark( 'dashboard' ) // Dashboard mockup
blockstudio_placeholder_dark( 'chart' ) // Chart illustration
blockstudio_placeholder_dark( 'product' ) // Product shot
Seiten zusammensetzen
Mit der <block>-Syntax setzen Seiten Blöcke zu vollständigen Layouts zusammen. Erstelle eine Startseite:
{
"name": "home",
"title": "Home",
"slug": "home",
"postType": "page",
"postStatus": "publish",
"templateLock": "all"
}
<block name="my-theme/hero"></block>
<block name="my-theme/features"></block>
Fertig. Jedes <block>-Element fügt den Block mit seinen Standardattributen ein. Führe wp bs pages sync aus, um den Seitenquelltext auf WordPress anzuwenden.
Um die Standardwerte für eine bestimmte Seite zu überschreiben, übergib die Attribute direkt:
<block name="my-theme/hero" heading="About Us" description="Our story and mission."></block>
<block name="my-theme/features" heading="Our Values"></block>
Wenn templateLock auf "all" gesetzt ist, können Kunden Blöcke weder hinzufügen noch entfernen oder neu anordnen. Die Seitenstruktur ist durch dein Template gesperrt. Weitere Sperrmodi und Bearbeitungsoptionen findest du unter Seiten.
Die Bibliothek erweitern
Eine einfache Bibliothek beginnt mit 3–5 Blöcken, eine umfangreiche umfasst 8–14. Hier sind die gängigen Blocktypen, ungefähr nach ihrer Häufigkeit geordnet:
| Block | Beschreibung | Wichtige Felder |
|---|---|---|
| Hero | Große Überschrift mit CTAs | Überschrift, Beschreibung, Links |
| Features | Raster mit Vorteilen | Überschrift, Repeater mit Titel und Beschreibung |
| CTA | Banner mit Handlungsaufforderung | Überschrift, Beschreibung, Link |
| Pricing | Tarifvergleich | Überschrift, Repeater mit Name, Preis und Features |
| Testimonials | Kundenstimmen | Repeater mit Zitat, Name und Rolle |
| FAQ | Aufklappbare Fragen | Überschrift, Repeater mit Frage und Antwort |
| Logos | Übersicht der Kundenlogos | Überschrift (Logos sind meist fest eingebundene SVGs) |
| Content | Abwechselnde Text- und Bildzeilen | Repeater mit Überschrift, Beschreibung und Bild |
| Showcase | Bild über die volle Breite mit Bildunterschrift | Überschrift, Beschreibung, Bild |
| Team | Raster mit Teammitgliedern | Überschrift, Repeater mit Name, Rolle und Bild |
| Stats | Zentrale Kennzahlen | Repeater mit Zahl und Beschriftung |
Jeder Block folgt demselben Muster: Tabs (Inhalt und Abschnitt), Gruppen für die Gliederung, Repeater für Listen und der Abschnitts-Helper für einheitliche Abstände. Wenn du zwei oder drei Blöcke erstellt hast, geht das Hinzufügen weiterer schnell von der Hand.
Weitere Seiten hinzufügen
Wenn deine Bibliothek wächst, kannst du aus denselben Blöcken verschiedene Seiten zusammensetzen:
<block name="my-theme/hero" heading="Simple, Transparent Pricing" description="Choose the plan that fits."></block>
<block name="my-theme/pricing"></block>
<block name="my-theme/faq" heading="Pricing FAQ"></block>
<block name="my-theme/cta"></block>
<block name="my-theme/hero" heading="About Us" description="Our story."></block>
<block name="my-theme/team"></block>
<block name="my-theme/testimonials"></block>
<block name="my-theme/cta" heading="Join Our Team"></block>
Dieselben Blöcke lassen sich mit unterschiedlichen Standardwerten für mehrere Seiten verwenden. Darin liegt der Vorteil einer Bibliothek: Du erstellst Blöcke einmal und setzt sie auf beliebig vielen Seiten zusammen.
Nächste Schritte
- Attribute registrieren: Vollständige Referenz zu Feldtypen und Eigenschaften
- Feldtypen: Alle verfügbaren Feldtypen
- Rezeptbuch für Feldmuster: Bedingte Gruppen, intelligente Auswahllisten und Repeater-Rezepte
- Seiten: Vorlagensperren, Bearbeitungsmodi und Zusammenführen nach Schlüssel
- Dateibasierte Seiten erstellen: Praktische Anleitung zu Seitentemplates und Synchronisierung
- Interaktivität: Verhalten auf der Client-Seite zu Blöcken hinzufügen