Vai al contenuto

Creare una libreria di blocchi

Una libreria di blocchi è un insieme di blocchi di sezione autonomi che, combinati, formano pagine complete. Ogni blocco gestisce il proprio schema, template e stile. Blockstudio fornisce il framework: elaborazione Tailwind CSS, registrazione degli attributi e sincronizzazione delle pagine. A voi spetta creare i blocchi.

Questa guida illustra come creare una libreria da zero, seguendo la stessa architettura usata in centinaia di temi in produzione. Alla fine avrete un tema funzionante con una hero, una griglia di funzionalità e una home page composta.

Struttura delle cartelle

Tutti i temi Blockstudio seguono la stessa struttura:

Codice
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

I blocchi si trovano in blockstudio/sections/. Ogni blocco è una cartella con uno schema block.json e un template index.php. Le pagine si trovano in pages/ e combinano i blocchi usando la sintassi <block>.

File di base

blockstudio.json

Questo file configura il modo in cui Blockstudio elabora il tema. La configurazione è uguale per tutti i temi:

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 rimuove gli stili predefiniti dei blocchi di WordPress. fullWidth imposta i tipi di contenuto page a larghezza intera. canvas attiva la modalità canvas dell’editor per un’esperienza di modifica più pulita.

Il campo tailwind.config è intenzionalmente vuoto. Con Tailwind v4, tutta la configurazione si trova in style.css secondo un approccio che privilegia CSS.

index.php

Il template WordPress principale. È WordPress standard, senza nulla di specifico per 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>

Aggiungete un header.php e un footer.php quando vi serve la navigazione. Per ora basta un template minimale per eseguire il rendering dei blocchi.

Token di design

Tutta la tematizzazione avviene in style.css usando la direttiva @theme di Tailwind v4. È il cuore del vostro sistema di design.

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

Ogni tema deve includere almeno:

Token Funzione
--font-sans o --font-serif Carattere principale
--color-bg Sfondo della pagina
--color-elevated Sfondo di schede e superfici
--color-subtle Bordi e separatori
--color-muted Testo secondario
--color-accent Colore principale del brand

Questi token generano automaticamente le utility Tailwind. --color-accent diventa bg-accent, text-accent, border-accent e così via.

Per un tema chiaro, invertite i valori:

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

Stili di base e utility

Sotto il blocco @theme, aggiungete gli stili per il body, i valori predefiniti del livello base e le utility personalizzate.

Gli stili del body devono stare fuori da @layer affinché l’editor WordPress li acquisisca:

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

Livello base per i valori predefiniti degli elementi:

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

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

	p {
		text-wrap: pretty;
	}
}

Utility personalizzate per schemi riutilizzabili. Ogni tema definisce un’utility container per mantenere coerente la spaziatura delle sezioni e, di norma, anche card, badge e utility per i pulsanti:

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

I selettori pseudo si inseriscono all’interno del blocco @utility usando il nesting CSS (&:hover). Non inserirli mai nel nome dell’utility. @utility btn-primary:hover {} non è valido e verrà rifiutato da Tailwind.

@source in linea

Blockstudio analizza automaticamente i template dei blocchi alla ricerca di classi Tailwind. Le classi usate al di fuori dei template dei blocchi (in functions.php, header.php, index.php) non vengono però individuate. Dichiaratele con @source inline:

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

Questo indica a Tailwind di includere queste classi nell’output anche se compaiono solo in file PHP non sottoposti ad analisi.

Lo schema delle sezioni

Lo schema delle sezioni è la convenzione più importante in una libreria di blocchi Blockstudio. Grazie a due meccanismi condivisi — un campo personalizzato e un helper PHP — offre a tutti i blocchi spaziature coerenti, la possibilità di alternare gli sfondi e il controllo dei margini interni.

Il campo della sezione

Create una definizione condivisa del campo a cui ogni blocco possa fare riferimento:

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

Questo campo compare nell’ispettore di ogni blocco, sotto la scheda «Section». Gli utenti dispongono di due controlli: attivare uno sfondo in risalto e rimuovere il margine interno inferiore, utile per impilare le sezioni senza spazi vuoti.

L’helper della sezione

In functions.php, create un helper che converta questi attributi in classi CSS:

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

Il template di ogni blocco richiama questo helper come prima istruzione. L’helper restituisce due stringhe di classi: una per l’elemento <section> esterno e una per il contenitore <div> interno.

Filtro di configurazione Tailwind

Sempre in functions.php, aggiungete il filtro che passa il vostro style.css al processore Tailwind di Blockstudio:

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

Questo indica a Blockstudio di usare il vostro style.css come origine della configurazione Tailwind v4. Senza di esso, i token @theme e le definizioni @utility non sarebbero disponibili nei template dei blocchi.

Il primo blocco: Hero

Una sezione Hero mostra lo schema completo di un blocco. Iniziate dallo 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" }
						]
					}
				]
			}
		]
	}
}

Schemi principali da notare:

Il wrapper tabs crea un ispettore con due schede: «Content» per i campi del blocco e «Section» per i controlli condivisi della sezione. Tutti i blocchi seguono questa struttura.

I campi sono organizzati in contenitori group. I gruppi separano visivamente i campi correlati nell’ispettore. Il primo gruppo contiene i campi di testo, il secondo quelli dei link.

I valori predefiniti offrono contenuti significativi, così il blocco appare completo appena viene inserito. È fondamentale quando si compongono le pagine, in cui i blocchi vengono aggiunti senza alcun intervento dell’utente.

Ora il 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>

Il template segue uno schema coerente:

  1. Richiamate l’helper della sezione per ottenere le classi CSS
  2. <section> esterno con useBlockProps e le classi della sezione
  3. <div> interno con le classi del contenitore
  4. Contenuto generato da $a (abbreviazione per gli attributi)
  5. Rendering condizionale dei campi facoltativi
  6. Escape corretto: esc_html() per il testo, esc_url() per gli URL, esc_attr() per gli attributi

Aggiungere ripetitori: griglia delle funzionalità

I ripetitori consentono agli utenti di aggiungere, rimuovere e riordinare gli elementi. Una griglia di funzionalità è l’esempio classico:

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

La proprietà textMinimized controlla quale testo appare quando una riga del ripetitore è compressa. Legge il valore del campo title e, se è vuoto, mostra «Feature». In questo modo l’ispettore resta utilizzabile anche con molti elementi.

L’array default fornisce gli elementi iniziali, visualizzati al primo inserimento del blocco. Fornite sempre valori predefiniti realistici, così il blocco apparirà subito completo.

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>

Gli elementi del ripetitore sono accessibili come un semplice array PHP. Usate foreach per il ciclo e accedete ai campi di ogni elemento tramite i rispettivi id.

Immagini e placeholder

Per i blocchi con immagini, usate il tipo di campo files e il componente MediaPlaceholder. Nel riquadro segnaposto dell’editor compare un’area per il trascinamento:

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

Nel template, eseguite il rendering dell’immagine con wp_get_attachment_image() e mostrate un SVG segnaposto se non è selezionata alcuna immagine:

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() restituisce un SVG in linea che usa currentColor con la variabile --color-accent, adattandosi automaticamente al tema. Per i temi chiari, usate blockstudio_placeholder_light(). Entrambi accettano un argomento variant:

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

Composizione delle pagine

Le pagine combinano i blocchi in layout completi tramite la sintassi <block>. Create una home page:

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>

È tutto. Ogni elemento <block> inserisce il blocco con i suoi valori predefiniti. Eseguite wp bs pages sync per applicare l’origine della pagina a WordPress.

Per sovrascrivere i valori predefiniti in una pagina specifica, passate direttamente gli attributi:

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

Con templateLock impostato su "all", gli utenti non possono aggiungere, rimuovere o riordinare i blocchi. La struttura della pagina è bloccata sul template. Consultate Pagine per altre modalità di blocco e controlli di modifica.

Crescita della libreria

Una libreria minimale parte da 3-5 blocchi; una libreria completa ne include 8-14. Ecco i tipi di blocco più comuni, approssimativamente in ordine di frequenza:

Blocco Descrizione Campi principali
Hero Titolo grande con CTA heading, description, links
Features Griglia di vantaggi heading, repeater con title + description
CTA Banner con invito all’azione heading, description, link
Pricing Confronto dei piani heading, repeater con name + price + features
Testimonials Citazioni dei clienti repeater con quote + name + role
FAQ Fisarmonica di domande heading, repeater con question + answer
Logos Raccolta di loghi dei clienti heading (i loghi sono di solito SVG inseriti direttamente nel codice)
Content Righe alternate di testo e immagini repeater con heading + description + image
Showcase Immagine a tutta larghezza con didascalia heading, description, image
Team Griglia di membri del team heading, repeater con name + role + image
Stats Metriche principali repeater con number + label

Ogni blocco segue lo stesso schema: schede (Content + Section), gruppi per organizzare i campi, ripetitori per gli elenchi e helper della sezione per mantenere spaziature coerenti. Dopo aver creato due o tre blocchi, aggiungerne altri diventa un’operazione meccanica.

Aggiungere altre pagine

Man mano che la libreria cresce, componete pagine diverse usando gli stessi blocchi:

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>

Gli stessi blocchi possono essere usati in più pagine, ciascuna con valori predefiniti diversi. È questo il vantaggio dell’approccio basato su libreria: create i blocchi una volta e combinateli in tutte le pagine che vi servono.

Passaggi successivi