Preskočiť na obsah

Tvorba knižnice blokov

Knižnica blokov je súbor samostatných blokov sekcií, z ktorých sa skladajú celé stránky. Každý blok obsahuje vlastnú schému, šablónu a štýly. Blockstudio poskytuje rámec: spracovanie Tailwind CSS, registráciu atribútov a synchronizáciu stránok. Bloky dodávate vy.

Táto príručka vás prevedie tvorbou knižnice od základov podľa rovnakej architektúry, aká sa používa v stovkách produkčných tém. Na konci budete mať funkčnú tému s úvodnou sekciou, mriežkou funkcií a zostavenou domovskou stránkou.

Štruktúra priečinkov

Každá téma Blockstudio má rovnaké rozloženie:

Kód
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

Bloky sa nachádzajú v blockstudio/sections/. Každý blok je priečinok so schémou block.json a šablónou index.php. Stránky sa nachádzajú v pages/ a skladajú bloky pomocou syntaxe <block>.

Základné súbory

blockstudio.json

Tento súbor určuje, ako Blockstudio spracúva vašu tému. Konfigurácia je rovnaká pre každú tému:

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 odstraňuje predvolené štýly blokov WordPress. fullWidth zabezpečuje, aby sa typy príspevkov page roztiahli na celú šírku. canvas zapína režim plátna editora pre prehľadnejšie úpravy.

Pole tailwind.config je zámerne prázdne. Pri použití Tailwind v4 sa všetka konfigurácia nachádza v style.css v prístupe, ktorý uprednostňuje CSS.

index.php

Hlavná šablóna WordPress. Ide o štandardné WordPress, nič špecifické pre 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>

Ak potrebujete navigáciu, pridajte header.php a footer.php. Zatiaľ na vykreslenie blokov postačí minimálna šablóna.

Dizajnové tokeny

Celé nastavenie témy prebieha v style.css pomocou direktívy Tailwind v4 s názvom @theme. Je to jadro vášho dizajnového systému.

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

Každá téma potrebuje minimálne:

Token Účel
--font-sans alebo --font-serif Základné písmo
--color-bg Pozadie stránky
--color-elevated Pozadie karty/povrchu
--color-subtle Orámovanie, oddeľovače
--color-muted Sekundárny text
--color-accent Primárna farba značky

Tieto tokeny automaticky vytvárajú pomocné triedy Tailwind. --color-accent sa zmení na bg-accent, text-accent, border-accent a podobne.

Pri svetlej téme obráťte hodnoty:

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

Základné štýly a pomocné triedy

Pod blok @theme pridajte štýly tela stránky, predvolené hodnoty základnej vrstvy a vlastné pomocné triedy.

Štýly tela stránky musia byť mimo @layer, aby ich editor WordPress prevzal:

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

Základná vrstva pre predvolené štýly prvkov:

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

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

	p {
		text-wrap: pretty;
	}
}

Vlastné pomocné triedy pre opakovane použiteľné vzory. Každá téma definuje pomocnú triedu container pre jednotné rozostupy sekcií a zvyčajne aj card, badge a pomocné triedy tlačidiel:

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ýbery patria do bloku @utility a používajú vnorenie CSS (&:hover). Nikdy ich nevkladajte do názvu pomocnej triedy. @utility btn-primary:hover {} je neplatné a Tailwind ho odmietne.

@source vložené

Blockstudio automaticky prehľadáva šablóny blokov a vyhľadáva triedy Tailwind. Triedy použité mimo šablón blokov (v functions.php, header.php, index.php) však neprehľadáva. Deklarujte ich pomocou @source inline:

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

Týmto poviete Tailwind, aby zahrnulo tieto triedy do výstupu, hoci sa nachádzajú iba v súboroch PHP, ktoré sa neprehľadávajú.

Vzor sekcie

Vzor sekcie je najdôležitejším pravidlom v knižnici blokov Blockstudio. Pomocou dvoch spoločných mechanizmov – vlastného poľa a pomocnej funkcie PHP – zabezpečuje jednotné rozostupy, prepínanie pozadia a ovládanie vnútorných okrajov pre každý blok.

Pole sekcie

Vytvorte spoločnú definíciu poľa, na ktorú sa môžu odkazovať všetky bloky:

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

Toto pole sa zobrazí v inšpektore každého bloku na karte „Sekcia“. Klienti získajú dva ovládacie prvky: prepnutie zvýrazneného pozadia a odstránenie spodného vnútorného okraja (užitočné pri skladaní sekcií bez medzier).

Pomocná funkcia sekcie

V functions.php vytvorte pomocnú funkciu, ktorá prevádza tieto atribúty na triedy 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 );
}

Každá šablóna bloku volá túto pomocnú funkciu hneď na prvom riadku. Funkcia vráti dva reťazce tried: jeden pre vonkajší prvok <section> a druhý pre vnútorný kontajner <div>.

Filter konfigurácie Tailwind

Aj v functions.php pridajte filter, ktorý odovzdá vaše style.css procesoru Blockstudio 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 '';
	}
);

Týmto poviete Blockstudio, aby použilo vaše style.css ako zdroj konfigurácie Tailwind v4. Bez toho by vaše tokeny @theme a definície @utility neboli dostupné v šablónach blokov.

Váš prvý blok: úvodná sekcia

Úvodná sekcia ukazuje kompletný vzor bloku. Začnite schémou:

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

Dôležité vzory:

Obal tabs vytvára inšpektor s dvoma kartami: „Obsah“ pre polia bloku a „Sekcia“ pre spoločné ovládacie prvky sekcie. Každý blok používa túto štruktúru.

Polia sa organizujú do kontajnerov group. Skupiny v inšpektore vizuálne oddeľujú súvisiace polia. Prvá skupina obsahuje textové polia, druhá polia odkazov.

Predvolené hodnoty poskytujú zmysluplný obsah, takže blok vyzerá kompletne hneď po vložení. Je to kľúčové pri skladaní stránok, keďže bloky sa pridávajú bez zásahu používateľa.

Teraz šablóna:

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>

Šablóna má jednotný vzor:

  1. Zavolajte pomocnú funkciu sekcie a získajte triedy CSS
  2. Vonkajší prvok <section> s useBlockProps a triedami sekcie
  3. Vnútorný prvok <div> s triedami kontajnera
  4. Vykreslite obsah z $a (skrátený zápis atribútov)
  5. Podmienené vykresľovanie voliteľných polí
  6. Správne escapovanie: esc_html() pre text, esc_url() pre adresy URL a esc_attr() pre atribúty

Pridávanie opakovačov: mriežka funkcií

Opakovače umožňujú klientom pridávať, odstraňovať a meniť poradie položiek. Klasickým príkladom je mriežka funkcií:

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

Vlastnosť textMinimized určuje, aký text sa zobrazí, keď je riadok opakovača zbalený. Načíta hodnotu poľa title, a ak je prázdne, použije „Funkcia“. Vďaka tomu sa dá inšpektor používať aj pri väčšom počte položiek.

Pole default poskytuje počiatočné položky, ktoré sa zobrazia pri prvom vložení bloku. Vždy nastavte realistické predvolené hodnoty, aby blok vyzeral kompletne hneď po vložení.

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>

K položkám opakovača sa pristupuje ako k obyčajnému poľu PHP. Opakujte pomocou foreach a k poliam jednotlivých položiek pristupujte cez ich id.

Obrázky a zástupné prvky

V blokoch s obrázkami použite typ poľa files a komponent MediaPlaceholder. Zástupný prvok zobrazí v editore oblasť na presúvanie súborov:

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

V šablóne vykreslite obrázok pomocou wp_get_attachment_image() a ak nie je vybraný žiadny obrázok, zobrazte zástupný SVG:

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() vráti vložený SVG, ktorý používa currentColor s premennou --color-accent, takže sa automaticky prispôsobí vašej téme. Pre svetlé témy použite blockstudio_placeholder_light(). Obe možnosti prijímajú argument variantu:

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

Skladanie stránok

Stránky sa skladajú do úplných rozložení pomocou syntaxe <block>. Vytvorte domovskú stránku:

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>

Hotovo. Každý prvok <block> vloží blok s predvolenými hodnotami atribútov. Spustením wp bs pages sync použijete zdroj stránky v WordPress.

Ak chcete zmeniť predvolené hodnoty pre konkrétnu stránku, zadajte atribúty priamo:

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

Ak je templateLock nastavené na "all", klienti nemôžu pridávať, odstraňovať ani meniť poradie blokov. Štruktúra stránky je uzamknutá podľa vašej šablóny. Ďalšie režimy uzamknutia a ovládacie prvky úprav nájdete v časti Stránky.

Rozšírenie knižnice

Minimálna knižnica začína s 3 až 5 blokmi. Komplexná knižnica ich má 8 až 14. Tu sú bežné typy blokov zoradené približne podľa toho, ako často sa používajú:

Blok Opis Kľúčové polia
Úvodná sekcia Veľký nadpis s výzvami na akciu nadpis, opis, odkazy
Funkcie Mriežka výhod nadpis, opakovač s názvom + opisom
CTA Banner s výzvou na akciu nadpis, opis, odkaz
Cenník Porovnanie plánov nadpis, opakovač s názvom + cenou + funkciami
Ohlasy Citáty zákazníkov opakovač s citátom + menom + rolou
FAQ Rozbaľovací zoznam otázok nadpis, opakovač s otázkou + odpoveďou
Logá Mrak log zákazníkov nadpis (logá sú zvyčajne pevne zakódované SVG)
Obsah Striedajúce sa riadky textu + obrázkov opakovač s nadpisom + opisom + obrázkom
Prehliadka Obrázok na celú šírku s popisom nadpis, opis, obrázok
Tím Mriežka členov tímu nadpis, opakovač s menom + rolou + obrázkom
Štatistiky Kľúčové metriky opakovač s číslom + označením

Každý blok používa rovnaký vzor: karty (Obsah + Sekcia), skupiny na usporiadanie, opakovače pre zoznamy a pomocnú funkciu sekcie pre jednotné rozostupy. Po vytvorení dvoch alebo troch blokov bude pridávanie ďalších rutinnou záležitosťou.

Pridávanie ďalších stránok

S rastúcou knižnicou skladajte z rovnakých blokov rôzne stránky:

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>

Rovnaké bloky slúžia viacerým stránkam, pričom každá má iné predvolené hodnoty. V tom spočíva sila prístupu založeného na knižnici: vytvorte bloky raz a skladajte z nich toľko stránok, koľko potrebujete.

Ďalšie kroky