Gå til indhold

Opbygning af et blokbibliotek

Et blokbibliotek er et sæt selvstændige sektionsblokke, der sættes sammen til hele sider. Hver blok har sit eget skema, sin egen skabelon og sine egne typografiske regler. Blockstudio leverer rammeværket: Tailwind CSS-behandling, attributregistrering og sidesynkronisering. Du leverer blokkene.

Denne vejledning gennemgår, hvordan du bygger et bibliotek fra bunden med samme arkitektur som i hundredvis af produktionstemaer. Når du er færdig, har du et fungerende tema med en hero, et funktionsgitter og en sammensat startside.

Mappestruktur

Alle Blockstudio-temaer følger samme struktur:

Kode
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

Blokkene ligger i blockstudio/sections/. Hver blok er en mappe med et block.json-skema og en index.php-skabelon. Siderne ligger i pages/ og sammensætter blokke med syntaksen <block>.

Grundfiler

blockstudio.json

Denne fil konfigurerer, hvordan Blockstudio behandler dit tema. Konfigurationen er den samme for alle temaer:

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 fjerner standardtypografier for WordPress-blokke. fullWidth får indholdstyperne page til at strække sig over hele bredden. canvas aktiverer editorens lærredstilstand for en mere overskuelig redigeringsoplevelse.

Feltet tailwind.config er bevidst tomt. Med Tailwind v4 ligger al konfiguration i style.css efter en tilgang, hvor CSS kommer først.

index.php

Den primære WordPress-skabelon. Dette er standard-WordPress, ikke noget særligt for Blockstudio:

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>

Tilføj en header.php og en footer.php, når du har brug for navigation. Indtil videre er en minimal skabelon nok til at gengive blokke.

Designtokens

Al tematisering foregår i style.css med direktivet Tailwind v4’s @theme. Det er kernen i dit designsystem.

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;
}

Alle temaer skal som minimum have:

Token Formål
--font-sans eller --font-serif Primær skrifttype
--color-bg Sidebaggrund
--color-elevated Baggrund for kort/overflader
--color-subtle Kanter og skillelinjer
--color-muted Sekundær tekst
--color-accent Primær brandfarve

Disse tokens genererer automatisk Tailwind-hjælpeklasser. --color-accent bliver til bg-accent, text-accent, border-accent osv.

Vend værdierne om for et lyst tema:

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;
}

Grundtypografier og hjælpeklasser

Under blokken @theme skal du tilføje typografier for body, standardværdier for basislaget og tilpassede hjælpeklasser.

Typografier for body skal stå uden for @layer, så editoren WordPress registrerer dem:

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

Basislaget til standardværdier for elementer:

CSS
@layer base {
	section {
		@apply relative overflow-hidden;
	}

	h1, h2, h3 {
		text-wrap: balance;
	}

	p {
		text-wrap: pretty;
	}
}

Tilpassede hjælpeklasser til genanvendelige mønstre. Alle temaer definerer en hjælpeklasse container til ensartet sektionsafstand og typisk også card, badge og hjælpeklasser til knapper:

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);
	}
}

Pseudovælgere skal stå inde i blokken @utility og bruge indlejring med CSS (&:hover). Sæt dem aldrig i navnet på hjælpeklassen. @utility btn-primary:hover {} er ugyldigt og afvises af Tailwind.

@source inline

Blockstudio scanner automatisk dine blokskabeloner for Tailwind-klasser. Men klasser, der bruges uden for blokskabelonerne (i functions.php, header.php, index.php), scannes ikke. Deklarer dem med @source inline:

CSS
@source inline("bg-bg bg-accent-tint container container-px container-no-pb");

Dette fortæller Tailwind, at disse klasser skal medtages i outputtet, selvom de kun findes i PHP-filer, der ikke scannes.

Sektionsmønsteret

Sektionsmønsteret er den vigtigste konvention i et blokbibliotek til Blockstudio. Det giver alle blokke ensartet afstand, mulighed for at skifte baggrund og kontrol over indvendig afstand via to fælles mekanismer: et brugerdefineret felt og en hjælpefunktion til PHP.

Sektionsfeltet

Opret en fælles feltdefinition, som alle blokke kan referere til:

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"
				}
			]
		}
	]
}

Dette felt vises i alle blokkes inspektør under fanen “Sektion”. Kunderne får to kontroller: én til at slå en fremhævet baggrund til og fra og én til at fjerne den indvendige afstand nederst (nyttigt, når sektioner stables uden mellemrum).

Sektionshjælpefunktionen

Opret i functions.php en hjælpefunktion, der omsætter disse attributter til CSS-klasser:

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 );
}

Hver blokskabelon kalder denne hjælpefunktion på første linje. Den returnerer to klassestrenge: én til det ydre <section>-element og én til den indre <div>-container.

Tailwind-konfigurationsfilter

Tilføj også i functions.php filteret, der sender din style.css til Blockstudios processor for Tailwind:

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 '';
	}
);

Dette fortæller Blockstudio, at din style.css skal bruges som konfigurationskilde for Tailwind v4. Uden det er dine @theme-tokens og @utility-definitioner ikke tilgængelige i blokskabelonerne.

Din første blok: Hero

En hero-sektion viser hele blokmønsteret. Begynd med skemaet:

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" }
						]
					}
				]
			}
		]
	}
}

Vigtige mønstre:

Wrapperen tabs opretter en inspektør med to faner: “Indhold” til blokkens felter og “Sektion” til de fælles sektionskontroller. Alle blokke bruger denne struktur.

Felterne organiseres i group-containere. Grupper adskiller visuelt relaterede felter i inspektøren. Den første gruppe indeholder tekstfelter, den anden linkfelter.

Standardværdier giver indholdet mening, så blokken ser færdig ud, så snart den indsættes. Det er afgørende, når sider sammensættes, fordi blokke tilføjes uden brugerinteraktion.

Nu til skabelonen:

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>

Skabelonen følger et fast mønster:

  1. Kald sektionshjælpefunktionen for at hente CSS-klasser
  2. Ydre <section> med useBlockProps og sektionsklasser
  3. Indre <div> med containerklasser
  4. Indhold gengivet fra $a (den korte attributsyntaks)
  5. Betinget gengivelse af valgfrie felter
  6. Korrekt escaping: esc_html() til tekst, esc_url() til URL’er, esc_attr() til attributter

Tilføjelse af gentagere: funktionsgitter

Gentagere lader kunder tilføje, fjerne og ændre rækkefølgen af elementer. Et funktionsgitter er det klassiske eksempel:

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" }
						]
					}
				]
			}
		]
	}
}

Egenskaben textMinimized styrer, hvilken tekst der vises, når en række i en gentager er foldet sammen. Den henter værdien fra feltet title og bruger “Funktion”, hvis feltet er tomt. Det gør inspektøren nem at bruge, når der er mange elementer.

Arrayet default indeholder de første elementer. De vises, første gang blokken indsættes. Angiv altid realistiske standardværdier, så blokken ser færdig ud med det samme.

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>

Gentagerelementer tilgås som et almindeligt PHP-array. Brug foreach til at gennemløbe dem, og tilgå hvert elements felter via deres id.

Billeder og pladsholdere

Brug felttypen files og komponenten MediaPlaceholder til blokke med billeder. Pladsholderen viser et træk-og-slip-område i editoren:

JSON
{
	"id": "image",
	"type": "files",
	"label": "Image"
}

Gengiv billedet i skabelonen med wp_get_attachment_image(), og vis en SVG-pladsholder, når der ikke er valgt et billede:

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() returnerer en inline-SVG, der bruger currentColor med variablen --color-accent, så den automatisk tilpasser sig dit tema. Brug blockstudio_placeholder_light() til lyse temaer. Begge accepterer et variantargument:

PHP
blockstudio_placeholder_dark( 'dashboard' )  // Dashboard mockup
blockstudio_placeholder_dark( 'chart' )      // Chart illustration
blockstudio_placeholder_dark( 'product' )    // Product shot

Sammensætning af sider

Sider sammensætter blokke til komplette layouts med syntaksen <block>. Opret en startside:

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>

Det var det. Hvert <block>-element indsætter blokken med dens standardattributværdier. Kør wp bs pages sync for at anvende sidekilden på WordPress.

Hvis du vil tilsidesætte standardværdierne for en bestemt side, skal du angive attributterne direkte:

PHP
<block name="my-theme/hero" heading="About Us" description="Our story and mission."></block>
<block name="my-theme/features" heading="Our Values"></block>

Når templateLock er sat til "all", kan kunderne ikke tilføje, fjerne eller flytte rundt på blokke. Sidens struktur er låst til din skabelon. Se Sider for andre låsetilstande og redigeringskontroller.

Skalering

Et minimalt bibliotek begynder med 3-5 blokke. Et omfattende bibliotek har 8-14. Her er almindelige bloktyper, omtrent sorteret efter hvor ofte de forekommer:

Blok Beskrivelse Vigtige felter
Hero Stor overskrift med CTA’er overskrift, beskrivelse, links
Funktioner Gitter med fordele overskrift, gentager med titel + beskrivelse
CTA Banner med handlingsopfordring overskrift, beskrivelse, link
Priser Sammenligning af abonnementer overskrift, gentager med navn + pris + funktioner
Udtalelser Kundeudtalelser gentager med citat + navn + rolle
FAQ Sammenklappelig liste med spørgsmål overskrift, gentager med spørgsmål + svar
Logoer Samling af kundelogoer overskrift (logoer er typisk SVG’er indsat direkte i koden)
Indhold Skiftevis rækker med tekst + billede gentager med overskrift + beskrivelse + billede
Fremvisning Billede i fuld bredde med billedtekst overskrift, beskrivelse, billede
Team Gitter med teammedlemmer overskrift, gentager med navn + rolle + billede
Statistik Nøgletal gentager med tal + betegnelse

Hver blok følger det samme mønster: faner (Indhold + Sektion), grupper til organisering, gentagere til lister og sektionshjælpefunktionen til ensartet afstand. Når du har bygget to eller tre blokke, bliver det rutine at tilføje flere.

Tilføjelse af flere sider

Efterhånden som biblioteket vokser, kan du sammensætte forskellige sider af de samme blokke:

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>

De samme blokke bruges på flere sider, hver med forskellige standardværdier. Det er styrken ved biblioteksmetoden: Byg blokke én gang, og sammensæt dem til så mange sider, du har brug for.

Næste trin