Bygga ett blockbibliotek
Ett blockbibliotek är en uppsättning fristående sektionsblock som sätts samman till hela sidor. Varje block har sitt eget schema, sin mall och sin formgivning. Blockstudio tillhandahåller ramverket: bearbetning av Tailwind CSS, attributregistrering och sidsynkronisering. Du tillhandahåller blocken.
Den här guiden går igenom hur du bygger ett bibliotek från grunden, enligt samma arkitektur som används i hundratals produktionsteman. När du är klar har du ett fungerande tema med en hero-sektion, ett funktionsrutnät och en sammansatt startsida.
Mappstruktur
Alla teman för Blockstudio följer samma layout:
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
Blocken finns i blockstudio/sections/. Varje block är en mapp med ett block.json-schema och en index.php-mall. Sidorna finns i pages/ och sätts samman med block enligt syntaxen <block>.
Grundfiler
blockstudio.json
Den här filen konfigurerar hur Blockstudio bearbetar ditt tema. Konfigurationen är densamma för alla teman:
{
"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 tar bort standardstilar för WordPress-block. fullWidth gör att inläggstyperna page sträcker sig över hela bredden. canvas aktiverar redigerarens arbetsyveläge för en renare redigeringsupplevelse.
Fältet tailwind.config är avsiktligt tomt. Med Tailwind v4 finns all konfiguration i style.css enligt en metod där CSS står i centrum.
index.php
Huvudmallen WordPress. Det här är vanlig WordPress, inget specifikt för 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>
Lägg till en header.php och en footer.php när du behöver navigering. För tillfället räcker en minimal mall för att rendera block.
Designtoken
All temastilning sker i style.css med direktivet Tailwind v4 @theme. Det här är kärnan i ditt 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;
}
Alla teman behöver minst:
| Token | Syfte |
|---|---|
--font-sans eller --font-serif |
Primärt typsnitt |
--color-bg |
Sidbakgrund |
--color-elevated |
Kort-/ytbakgrund |
--color-subtle |
Kantlinjer, avdelare |
--color-muted |
Sekundär text |
--color-accent |
Primär varumärkesfärg |
Dessa token genererar automatiskt Tailwind-verktygsklasser. --color-accent blir bg-accent, text-accent, border-accent och så vidare.
För ett ljust tema vänder du på värdena:
@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;
}
Grundstilar och verktygsklasser
Lägg till formatmallar för body, standardvärden för grundlagret och anpassade verktygsklasser under blocket @theme.
Body-formatmallar måste ligga utanför @layer så att redigeraren WordPress hämtar upp dem:
body {
@apply bg-bg font-sans text-white antialiased;
}
Grundlager för standardvärden för element:
@layer base {
section {
@apply relative overflow-hidden;
}
h1, h2, h3 {
text-wrap: balance;
}
p {
text-wrap: pretty;
}
}
Anpassade verktygsklasser för återanvändbara mönster. Varje tema definierar en container-verktygsklass för enhetligt avstånd mellan sektioner, och vanligtvis även card-, badge– och knappverktygsklasser:
@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);
}
}
Pseudoselektorer ska ligga inuti blocket @utility och använda nästling enligt CSS (&:hover). Lägg dem aldrig i verktygsklassens namn. @utility btn-primary:hover {} är ogiltigt och avvisas av Tailwind.
@source inline
Blockstudio söker automatiskt igenom dina blockmallar efter klasser i Tailwind. Men klasser som används utanför blockmallarna (i functions.php, header.php, index.php) söks inte igenom. Deklarera dem med @source inline:
@source inline("bg-bg bg-accent-tint container container-px container-no-pb");
Detta talar om för Tailwind att inkludera dessa klasser i resultatet, trots att de bara förekommer i filer av typen PHP som inte genomsöks.
Sektionsmönstret
Sektionsmönstret är den viktigaste konventionen i ett blockbibliotek för Blockstudio. Det ger alla block enhetliga avstånd, möjlighet att växla bakgrund och kontroll över utfyllnad genom två gemensamma mekanismer: ett anpassat fält och en hjälpfunktion för PHP.
Sektionsfältet
Skapa en gemensam fältdefinition som alla block kan använda:
{
"$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"
}
]
}
]
}
Det här fältet visas i varje blocks granskningspanel under fliken “Section”. Kunderna får två kontroller: växla accentbakgrund och ta bort utfyllnad längst ned (användbart när sektioner staplas utan mellanrum).
Sektionshjälpfunktionen
Skapa en hjälpfunktion i functions.php som omvandlar dessa attribut till klasser i 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 );
}
Varje blockmall anropar den här hjälpfunktionen på första raden. Hjälpfunktionen returnerar två klasssträngar: en för det yttre <section>-elementet och en för den inre behållaren <div>.
Tailwind konfigurationsfilter
Lägg även till filtret i functions.php som skickar ditt style.css till processorn för Blockstudio 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 '';
}
);
Detta talar om för Blockstudio att använda ditt style.css som konfigurationskälla för Tailwind v4. Utan det skulle dina @theme-token och @utility-definitioner inte vara tillgängliga i blockmallarna.
Ditt första block: Hero
En hero-sektion visar hela blockmönstret. Börja med schemat:
{
"$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" }
]
}
]
}
]
}
}
Viktiga mönster att lägga märke till:
Omslaget tabs skapar en granskningspanel med två flikar: “Content” för blockets fält och “Section” för de gemensamma sektionskontrollerna. Alla block använder den här strukturen.
Fälten ordnas i behållare av typen group. Grupper skiljer visuellt åt relaterade fält i granskningspanelen. Den första gruppen innehåller textfält och den andra länkfält.
Standardvärdena ger meningsfullt innehåll så att blocket ser komplett ut direkt när det infogas. Det är viktigt när sidor sätts samman, eftersom block läggs till utan att användaren behöver göra något.
Nu till mallen:
<?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>
Mallen följer ett enhetligt mönster:
- Anropa sektionshjälpfunktionen för att hämta klasser för CSS
- Yttre
<section>meduseBlockPropsoch sektionsklasser - Inre
<div>med behållarklasser - Innehåll renderat från
$a(kortformen för attribut) - Villkorlig rendering av valfria fält
- Korrekt escaping:
esc_html()för text,esc_url()för URL:er,esc_attr()för attribut
Lägga till upprepningsfält: funktionsrutnät
Upprepningsfält låter kunder lägga till, ta bort och ändra ordning på objekt. Ett funktionsrutnät är det klassiska exemplet:
{
"$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" }
]
}
]
}
]
}
}
Egenskapen textMinimized styr vilken text som visas när en rad i ett upprepningsfält är hopfälld. Den läser fältvärdet title och visar “Feature” om det är tomt. Det gör granskningspanelen lättare att använda när du har många objekt.
Matrisen default innehåller startobjekt. De visas när blocket infogas första gången. Ange alltid realistiska standardvärden så att blocket ser komplett ut direkt.
<?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>
Objekten i upprepningsfältet nås som en vanlig PHP-matris. Iterera med foreach och kom åt varje objekts fält via deras id.
Bilder och platshållare
För block med bilder använder du fälttypen files och komponenten MediaPlaceholder. Platshållaren visar en dra-och-släpp-yta i redigeraren:
{
"id": "image",
"type": "files",
"label": "Image"
}
Rendera bilden i mallen med wp_get_attachment_image() och visa en platshållar-SVG när ingen bild har valts:
<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() returnerar en inbäddad SVG som använder currentColor med variabeln --color-accent, så den anpassas automatiskt till temat. För ljusa teman använder du blockstudio_placeholder_light(). Båda accepterar ett variantargument:
blockstudio_placeholder_dark( 'dashboard' ) // Dashboard mockup
blockstudio_placeholder_dark( 'chart' ) // Chart illustration
blockstudio_placeholder_dark( 'product' ) // Product shot
Sätta samman sidor
Sidor sätts samman av block till kompletta layouter med syntaxen <block>. Skapa en startsida:
{
"name": "home",
"title": "Home",
"slug": "home",
"postType": "page",
"postStatus": "publish",
"templateLock": "all"
}
<block name="my-theme/hero"></block>
<block name="my-theme/features"></block>
Klart. Varje element av typen <block> infogar blocket med dess standardvärden för attribut. Kör wp bs pages sync för att tillämpa sidkällan på WordPress.
Om du vill åsidosätta standardvärden för en viss sida skickar du attribut direkt:
<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 är inställt på "all" kan kunder inte lägga till, ta bort eller ändra ordning på block. Sidstrukturen låses till din mall. Se Pages för andra låslägen och redigeringskontroller.
Skala upp
Ett minimalt bibliotek börjar med 3–5 block. Ett heltäckande bibliotek har 8–14. Här är vanliga blocktyper, ungefär i ordning efter hur ofta de förekommer:
| Block | Beskrivning | Viktiga fält |
|---|---|---|
| Hero | Stor rubrik med CTA:er | rubrik, beskrivning, länkar |
| Features | Rutnät med fördelar | rubrik, upprepningsfält med titel + beskrivning |
| CTA | Uppmaningsbanner | rubrik, beskrivning, länk |
| Pricing | Jämförelse av planer | rubrik, upprepningsfält med namn + pris + funktioner |
| Testimonials | Kundcitat | upprepningsfält med citat + namn + roll |
| FAQ | Dragspelsmeny med frågor | rubrik, upprepningsfält med fråga + svar |
| Logos | Samling av kundlogotyper | rubrik (logotyperna är vanligtvis hårdkodade SVG-filer) |
| Content | Växlande rader med text + bild | upprepningsfält med rubrik + beskrivning + bild |
| Showcase | Bild i full bredd med bildtext | rubrik, beskrivning, bild |
| Team | Rutnät med teammedlemmar | rubrik, upprepningsfält med namn + roll + bild |
| Stats | Nyckeltal | upprepningsfält med nummer + etikett |
Alla block följer samma mönster: flikar (Content + Section), grupper för organisering, upprepningsfält för listor och sektionshjälpfunktionen för enhetliga avstånd. När du har byggt två eller tre block går det på rutin att lägga till fler.
Lägga till fler sidor
När biblioteket växer kan du sätta samman olika sidor av samma block:
<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>
Samma block används på flera sidor, var och en med olika standardvärden. Det är styrkan i biblioteksmetoden: bygg blocken en gång och sätt sedan samman så många sidor du behöver.
Nästa steg
- Registrera attribut: fullständig referens för fälttyper och egenskaper
- Fälttyper: alla tillgängliga fälttyper
- Fältexempelsamling: villkorliga grupper, smarta listval och recept för upprepningsfält
- Pages: mallås, redigeringslägen och sammanslagning efter nyckel
- Skapa filbaserade sidor: praktisk genomgång av sidmallar och synkronisering
- Interaktivitet: lägg till beteende på klientsidan i block