Zum Inhalt springen

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:

Code
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:

JSON
{
	"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:

PHP
<!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.

CSS
/*
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:

CSS
@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:

CSS
body {
	@apply bg-bg font-sans text-white antialiased;
}

Basisebene für Standardwerte von Elementen:

CSS
@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:

CSS
@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:

CSS
@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:

JSON
{
	"$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
<?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:

PHP
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:

JSON
{
	"$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
<?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:

  1. Rufe den Abschnitts-Helper auf, um CSS-Klassen zu erhalten
  2. Äußeres <section> mit useBlockProps und Abschnittsklassen
  3. Inneres <div> mit Containerklassen
  4. Inhalt aus $a ausgeben (Kurzschreibweise für Attribute)
  5. Optionale Felder bedingt ausgeben
  6. 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:

JSON
{
	"$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
<?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:

JSON
{
	"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:

PHP
<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:

PHP
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:

JSON
{
	"name": "home",
	"title": "Home",
	"slug": "home",
	"postType": "page",
	"postStatus": "publish",
	"templateLock": "all"
}
PHP
<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:

PHP
<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:

PHP
<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>
PHP
<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