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:
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:
{
"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:
<!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.
/*
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:
@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:
body {
@apply bg-bg font-sans text-white antialiased;
}
Basislaget til standardværdier for elementer:
@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:
@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:
@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:
{
"$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
/**
* 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:
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:
{
"$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 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:
- Kald sektionshjælpefunktionen for at hente CSS-klasser
- Ydre
<section>meduseBlockPropsog sektionsklasser - Indre
<div>med containerklasser - Indhold gengivet fra
$a(den korte attributsyntaks) - Betinget gengivelse af valgfrie felter
- 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:
{
"$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 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:
{
"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:
<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:
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:
{
"name": "home",
"title": "Home",
"slug": "home",
"postType": "page",
"postStatus": "publish",
"templateLock": "all"
}
<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:
<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:
<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>
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
- Registrering af attributter: komplet reference til felttyper og egenskaber
- Felttyper: alle tilgængelige felttyper
- Felter i praksis: betingede grupper, smarte valglister og opskrifter på gentagere
- Sider: skabelonlåsning, redigeringstilstande og sammenfletning efter nøgler
- Opbygning af filbaserede sider: praktisk gennemgang af sideskabeloner og synkronisering
- Interaktivitet: tilføjelse af klientadfærd til blokke