Een blokbibliotheek bouwen
Een blokbibliotheek is een set zelfstandige sectieblokken die samen volledige pagina’s vormen. Elk blok beheert zijn eigen schema, template en stijlen. Blockstudio biedt het framework: Tailwind CSS-verwerking, attribuutregistratie en paginasynchronisatie. U levert de blokken.
Deze gids laat zien hoe u vanaf nul een bibliotheek bouwt, volgens dezelfde architectuur die in honderden productiethema’s wordt gebruikt. Aan het eind hebt u een werkend thema met een hero, een raster met functies en een samengestelde startpagina.
Mapstructuur
Elk Blockstudio-thema volgt dezelfde indeling:
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
Blokken staan in blockstudio/sections/. Elk blok is een map met een schema in block.json en een template in index.php. Pagina’s staan in pages/ en combineren blokken met de syntaxis <block>.
Basisbestanden
blockstudio.json
Dit bestand configureert hoe Blockstudio uw thema verwerkt. De configuratie is voor elk thema hetzelfde:
{
"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 verwijdert de standaardstijlen van WordPress-blokken. fullWidth zorgt ervoor dat page-berichttypen de volledige breedte benutten. canvas schakelt de canvasmodus van de editor in voor een overzichtelijkere bewerkingservaring.
Het veld tailwind.config is bewust leeg. Met Tailwind v4 staat alle configuratie in style.css, volgens de aanpak waarbij CSS centraal staat.
index.php
De hoofdtemplate WordPress. Dit is standaard WordPress, niets dat specifiek is voor 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>
Voeg header.php en footer.php toe als u navigatie nodig hebt. Voor nu volstaat een minimale template om blokken te renderen.
Ontwerptokens
Alle thematisering gebeurt in style.css met de richtlijn Tailwind v4 @theme. Dit is het hart van uw ontwerpsysteem.
/*
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;
}
Elk thema heeft minimaal het volgende nodig:
| Token | Doel |
|---|---|
--font-sans of --font-serif |
Primair lettertype |
--color-bg |
Achtergrond van de pagina |
--color-elevated |
Achtergrond van kaarten en oppervlakken |
--color-subtle |
Randen en scheidingslijnen |
--color-muted |
Secundaire tekst |
--color-accent |
Primaire merkkleur |
Deze tokens genereren automatisch Tailwind-hulpprogrammaklassen. --color-accent wordt bg-accent, text-accent, border-accent enzovoort.
Draai de waarden om voor een licht thema:
@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;
}
Basisstijlen en hulpprogramma’s
Voeg onder het @theme-blok stijlen voor de body, standaardwaarden voor de basislaag en aangepaste hulpprogrammaklassen toe.
Body-stijlen moeten buiten @layer staan, zodat de editor van WordPress ze oppikt:
body {
@apply bg-bg font-sans text-white antialiased;
}
Basislaag voor standaardwaarden van elementen:
@layer base {
section {
@apply relative overflow-hidden;
}
h1, h2, h3 {
text-wrap: balance;
}
p {
text-wrap: pretty;
}
}
Aangepaste hulpprogrammaklassen voor herbruikbare patronen. Elk thema definieert een hulpprogrammaklasse container voor consistente afstand tussen secties, en meestal ook card, badge en klassen voor knoppen:
@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);
}
}
Pseudoselectors staan binnen het blok @utility en gebruiken nesting van CSS (&:hover). Zet ze nooit in de naam van een hulpprogrammaklasse. @utility btn-primary:hover {} is ongeldig en wordt afgewezen door Tailwind.
Inline @source
Blockstudio scant uw bloktemplates automatisch op Tailwind-klassen. Maar klassen die buiten bloktemplates worden gebruikt (in functions.php, header.php, index.php) worden niet gescand. Declareer ze met @source inline:
@source inline("bg-bg bg-accent-tint container container-px container-no-pb");
Hierdoor neemt Tailwind deze klassen op in de uitvoer, ook al komen ze alleen voor in PHP-bestanden die niet worden gescand.
Het sectiepatroon
Het sectiepatroon is de belangrijkste conventie in een Blockstudio-blokbibliotheek. Het biedt elk blok consistente afstand, een omschakelbare achtergrond en controle over de opvulling via twee gedeelde mechanismen: een aangepast veld en een helper van PHP.
Het sectieveld
Maak een gedeelde velddefinitie waarnaar elk blok kan verwijzen:
{
"$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"
}
]
}
]
}
Dit veld staat in de inspector van elk blok onder een tabblad ‘Sectie’. Klanten krijgen twee bedieningselementen: een accentachtergrond in- of uitschakelen en de ondermarge verwijderen (handig om secties zonder tussenruimte op elkaar te laten aansluiten).
De sectiehelper
Maak in functions.php een helper die deze attributen omzet in klassen van CSS:
<?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 );
}
Elke bloktemplate roept deze helper aan op de eerste regel. De helper retourneert twee klassentekenreeksen: één voor het buitenste element <section> en één voor de binnenste container <div>.
Het configuratiefilter van Tailwind
Voeg ook in functions.php het filter toe dat uw style.css doorgeeft aan de Tailwind-processor van Blockstudio:
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 '';
}
);
Hierdoor gebruikt Blockstudio uw style.css als de bron voor de configuratie van Tailwind v4. Zonder dit filter zijn uw tokens @theme en definities van @utility niet beschikbaar in bloktemplates.
Uw eerste blok: Hero
Een hero-sectie laat het volledige blokpatroon zien. Begin met het 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" }
]
}
]
}
]
}
}
Belangrijke patronen:
De wrapper tabs maakt een inspector met twee tabbladen: ‘Content’ voor de velden van het blok en ‘Sectie’ voor de gedeelde sectiebedieningselementen. Elk blok gebruikt deze structuur.
Velden zijn ingedeeld in containers van group. Groepen scheiden verwante velden visueel in de inspector. De eerste groep bevat tekstvelden, de tweede linkvelden.
Standaardwaarden bieden betekenisvolle content, zodat het blok er compleet uitziet zodra het wordt ingevoegd. Dit is cruciaal bij het samenstellen van pagina’s, waarbij blokken zonder tussenkomst van de gebruiker worden toegevoegd.
Nu de 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>
De template volgt een vast patroon:
- Roep de sectiehelper aan om klassen van CSS op te halen
- Buitenste
<section>metuseBlockPropsen sectieklassen - Binnenste
<div>met containerklassen - Content gerenderd vanuit
$a(de verkorte notatie voor attributen) - Voorwaardelijk renderen van optionele velden
- Correct escapen:
esc_html()voor tekst,esc_url()voor URL’s,esc_attr()voor attributen
Herhalers toevoegen: raster met functies
Met herhalers kunnen klanten items toevoegen, verwijderen en de volgorde ervan wijzigen. Een raster met functies is het klassieke voorbeeld:
{
"$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" }
]
}
]
}
]
}
}
De eigenschap textMinimized bepaalt welke tekst wordt weergegeven wanneer een rij van de herhaler is ingeklapt. De eigenschap leest de waarde van het veld title en gebruikt ‘Functie’ als die leeg is. Zo blijft de inspector bruikbaar wanneer u veel items hebt.
De array default bevat de beginitems. Deze verschijnen wanneer het blok voor het eerst wordt ingevoegd. Geef altijd realistische standaardwaarden op, zodat het blok er meteen compleet uitziet.
<?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>
Items uit een herhaler zijn toegankelijk als een gewone array van PHP. Gebruik foreach voor de lus en benader de velden van elk item via hun id.
Afbeeldingen en tijdelijke aanduidingen
Gebruik voor blokken met afbeeldingen het veldtype files en de component MediaPlaceholder. De tijdelijke aanduiding toont in de editor een zone waarin u items kunt slepen en neerzetten:
{
"id": "image",
"type": "files",
"label": "Image"
}
Render de afbeelding in de template met wp_get_attachment_image() en toon een tijdelijke SVG-aanduiding als er geen afbeelding is geselecteerd:
<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() retourneert een inline SVG dat currentColor met de variabele --color-accent gebruikt, zodat het zich automatisch aan uw thema aanpast. Gebruik voor lichte thema’s blockstudio_placeholder_light(). Beide accepteren een variantargument:
blockstudio_placeholder_dark( 'dashboard' ) // Dashboard mockup
blockstudio_placeholder_dark( 'chart' ) // Chart illustration
blockstudio_placeholder_dark( 'product' ) // Product shot
Pagina’s samenstellen
Pagina’s combineren blokken tot volledige layouts met de syntaxis <block>. Maak een startpagina:
{
"name": "home",
"title": "Home",
"slug": "home",
"postType": "page",
"postStatus": "publish",
"templateLock": "all"
}
<block name="my-theme/hero"></block>
<block name="my-theme/features"></block>
Dat is alles. Elk element <block> voegt het blok met zijn standaard attribuutwaarden in. Voer wp bs pages sync uit om de paginabron toe te passen op WordPress.
Geef attributen rechtstreeks door om standaardwaarden voor een specifieke pagina te overschrijven:
<block name="my-theme/hero" heading="About Us" description="Our story and mission."></block>
<block name="my-theme/features" heading="Our Values"></block>
Als templateLock is ingesteld op "all", kunnen klanten geen blokken toevoegen, verwijderen of verplaatsen. De paginastructuur is vergrendeld volgens uw template. Zie Pagina’s voor andere vergrendelingsmodi en bewerkingsopties.
Opschalen
Een minimale bibliotheek begint met 3-5 blokken. Een uitgebreide bibliotheek heeft er 8-14. Dit zijn veelvoorkomende bloktypen, ongeveer gerangschikt naar hoe vaak ze voorkomen:
| Blok | Beschrijving | Belangrijke velden |
|---|---|---|
| Hero | Grote kop met CTA’s | kop, beschrijving, links |
| Functies | Raster met voordelen | kop, herhaler met titel en beschrijving |
| CTA | Banner met oproep tot actie | kop, beschrijving, link |
| Prijzen | Vergelijking van abonnementen | kop, herhaler met naam, prijs en functies |
| Ervaringen | Citaten van klanten | herhaler met citaat, naam en functie |
| Veelgestelde vragen | Accordeon met vragen | kop, herhaler met vraag en antwoord |
| Logo’s | Verzameling logo’s van klanten | kop (logo’s zijn doorgaans hardgecodeerde SVG’s) |
| Content | Rijen met afwisselend tekst en afbeelding | herhaler met kop, beschrijving en afbeelding |
| Showcase | Afbeelding over de volledige breedte met bijschrift | kop, beschrijving, afbeelding |
| Team | Raster met teamleden | kop, herhaler met naam, functie en afbeelding |
| Statistieken | Belangrijke meetwaarden | herhaler met getal en label |
Elk blok volgt hetzelfde patroon: tabbladen (Content en Sectie), groepen voor de indeling, herhalers voor lijsten en de sectiehelper voor consistente afstand. Als u eenmaal twee of drie blokken hebt gebouwd, is meer toevoegen routinewerk.
Meer pagina’s toevoegen
Naarmate uw bibliotheek groeit, kunt u verschillende pagina’s met dezelfde blokken samenstellen:
<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>
Dezelfde blokken kunnen meerdere pagina’s vormen, elk met andere standaardwaarden. Dat is de kracht van de bibliotheekaanpak: bouw blokken één keer en stel er zo veel pagina’s mee samen als u nodig hebt.
Volgende stappen
- Attributen registreren: complete referentie voor veldtypen en eigenschappen
- Veldtypen: alle beschikbare veldtypen
- Kookboek voor veldpatronen: voorwaardelijke groepen, slimme keuzelijsten en recepten voor herhalers
- Pagina’s: templates vergrendelen, bewerkingsmodi en samenvoegen op basis van sleutels
- Pagina’s op basis van bestanden bouwen: praktische handleiding voor paginatemplates en synchronisatie
- Interactiviteit: gedrag aan de clientzijde toevoegen aan blokken