Ugrás a tartalomhoz

Blokkkönyvtár építése

A blokkkönyvtár önálló szekcióblokkok készlete, amelyek teljes oldalakká állnak össze. Minden blokkhoz saját séma, sablon és stílus tartozik. A Blockstudio biztosítja a keretrendszert: Tailwind CSS feldolgozás, attribútumregisztráció és oldalszinkronizálás. A blokkokat Ön készíti el.

Ez az útmutató végigvezet egy könyvtár nulláról történő felépítésén, a több száz éles témában használt architektúrát követve. A végére egy működő témája lesz hős szekcióval, funkciórácsokkal és összeállított kezdőlappal.

Mappastruktúra

Minden Blockstudio téma ugyanazt az elrendezést követi:

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

A blokkok a blockstudio/sections/ mappában találhatók. Minden blokk egy mappa, benne block.json sémával és index.php sablonnal. Az oldalak a pages/ mappában vannak, és a <block> szintaxissal állítják össze a blokkokat.

Alapfájlok

blockstudio.json

Ez a fájl szabályozza, hogyan dolgozza fel a Blockstudio a témát. A konfiguráció minden témánál azonos:

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

Az reset eltávolítja az alapértelmezett WordPress blokkstílusokat. Az fullWidth teljes szélességűre állítja a page bejegyzéstípusokat. Az canvas engedélyezi a szerkesztővászon módot a letisztultabb szerkesztési élményért.

Az tailwind.config mező szándékosan üres. Az Tailwind v4 használatával minden konfiguráció az style.css fájlban él, a CSS-központú megközelítést követve.

index.php

A fő WordPress sablon. Ez szabványos WordPress, semmi Blockstudio-specifikus nincs benne:

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>

Adjon hozzá egy header.php és egy footer.php elemet, ha navigációra van szüksége. Egyelőre a minimális sablon is elegendő a blokkok rendereléséhez.

Dizájn tokenek

Minden témázás a style.css fájlban történik, a Tailwind v4 @theme direktívájával. Ez a dizájnrendszer központi eleme.

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

Minden témának legalább ezekre van szüksége:

Token Rendeltetés
--font-sans vagy --font-serif Elsődleges betűtípus
--color-bg Oldal háttere
--color-elevated Kártya/felület háttere
--color-subtle Szegélyek, elválasztók
--color-muted Másodlagos szöveg
--color-accent Elsődleges márkaszín

Ezek a tokenek automatikusan létrehozzák a Tailwind segédosztályokat. Az --color-accent értéke bg-accent, text-accent, border-accent és így tovább lesz.

Világos témához fordítsa meg az értékeket:

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

Alapstílusok és segédosztályok

Az @theme blokk után adja hozzá a törzs stílusait, az alapréteg alapértelmezéseit és az egyéni segédosztályokat.

A törzs stílusait az @layer blokkon kívül kell elhelyezni, hogy az WordPress szerkesztő is alkalmazza őket:

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

Alapréteg az elemek alapértelmezéseihez:

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

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

	p {
		text-wrap: pretty;
	}
}

Egyéni segédosztályok az újrafelhasználható mintákhoz. Minden téma definiál egy container segédosztályt a következetes szekcióközökért, jellemzően továbbá card, badge és gombsegédosztályokat is:

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

Az ál-szelektorok az @utility blokkon belülre kerüljenek, a CSS beágyazási szintaxissal (&:hover). Soha ne tegye őket a segédosztály nevébe. Az @utility btn-primary:hover {} érvénytelen, és a Tailwind elutasítja.

@source beágyazottan

A Blockstudio automatikusan átvizsgálja a blokk sablonjait, és megkeresi bennük az Tailwind osztályokat. A blokksablonokon kívül használt osztályokat (az functions.php, header.php, index.php fájlokban) viszont nem vizsgálja át. Ezeket a @source inline segítségével deklarálja:

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

Ezzel arra utasítja a Tailwind rendszert, hogy ezeket az osztályokat akkor is belefoglalja a kimenetbe, ha csak át nem vizsgált PHP fájlokban fordulnak elő.

A szekcióminta

A szekcióminta a Blockstudio blokkkönyvtár legfontosabb konvenciója. Két közös mechanizmussal biztosít egységes térközöket, váltható hátteret és szabályozható belső margót minden blokkban: egy egyéni mezővel és egy PHP segédfüggvénnyel.

A szekciómező

Hozzon létre egy közös meződefiníciót, amelyre minden blokk hivatkozhat:

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

Ez a mező minden blokk szerkesztőpaneljén megjelenik egy „Szekció” fülön. Az ügyfelek két vezérlőelemet kapnak: bekapcsolhatják a kiemelő hátteret, illetve eltávolíthatják az alsó belső margót (ez hasznos a hézagmentesen egymásra illesztett szekcióknál).

A szekció-segédfüggvény

A functions.php fájlban hozzon létre egy segédfüggvényt, amely ezeket az attribútumokat CSS osztályokká alakítja:

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

Minden blokk sablonjának első sorában ezt a segédfüggvényt kell meghívni. Két osztálykarakterláncot ad vissza: egyet a külső <section> elemhez, egyet pedig a belső <div> konténerhez.

Tailwind konfigurációs szűrő

Szintén az functions.php fájlban adja hozzá a szűrőt, amely továbbítja a style.css tartalmát a Blockstudio Tailwind feldolgozójának:

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

Ezzel arra utasítja a Blockstudio rendszert, hogy a style.css legyen a Tailwind v4 konfigurációs forrása. Enélkül a @theme tokenek és a @utility definíciók nem lennének elérhetők a blokksablonokban.

Az első blokk: Hero

A hero szekció bemutatja a teljes blokkmintát. Kezdje a sémával:

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

Figyelje meg a következő mintákat:

Az tabs burkoló kétfüles szerkesztőpanelt hoz létre: a „Tartalom” fülön találhatók a blokk mezői, a „Szekció” fülön pedig a közös szekcióvezérlők. Minden blokk ezt a szerkezetet használja.

A mezők group konténerekbe vannak rendezve. A csoportok vizuálisan különítik el az összetartozó mezőket a szerkesztőpanelen. Az első csoport szövegmezőket, a második hivatkozásmezőket tartalmaz.

Az alapértelmezett értékek értelmes tartalmat adnak, így a blokk már beillesztéskor teljesnek tűnik. Ez elengedhetetlen az oldalak összeállításánál, amikor a blokkok felhasználói beavatkozás nélkül kerülnek be.

Most jöjjön a sablon:

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>

A sablon következetes mintát követ:

  1. Hívja meg a szekció-segédfüggvényt az CSS osztályok lekéréséhez
  2. Külső <section> elem useBlockProps attribútummal és szekcióosztályokkal
  3. Belső <div> elem konténerosztályokkal
  4. Az $a-ből renderelt tartalom (az attribútumok rövid jelölése)
  5. Feltételes renderelés az opcionális mezőkhöz
  6. Helyes escape-elés: esc_html() a szöveghez, esc_url() az URL-ekhez, esc_attr() az attribútumokhoz

Ismétlők hozzáadása: funkciórács

Az ismétlőkkel az ügyfelek elemeket adhatnak hozzá, távolíthatnak el és rendezhetnek át. A funkciórács klasszikus példa erre:

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

Az textMinimized tulajdonság szabályozza, milyen szöveg látható összecsukott ismétlősornál. Az title mező értékét olvassa be, üres érték esetén pedig a „Funkció” szót jeleníti meg. Ez sok elem esetén is használhatóvá teszi a szerkesztőpanelt.

Az default tömb adja meg a kezdeti elemeket. Ezek a blokk első beillesztésekor jelennek meg. Mindig reális alapértékeket adjon meg, hogy a blokk azonnal teljesnek tűnjön.

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>

Az ismétlőelemek egyszerű PHP tömbként érhetők el. A bejáráshoz használja a foreach elemet, az egyes elemek mezőit pedig a id alapján érheti el.

Képek és helyőrzők

Képeket tartalmazó blokkoknál használja az files mezőtípust és az MediaPlaceholder komponenst. A helyőrző fogd és vidd területet jelenít meg a szerkesztőben:

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

A sablonban az wp_get_attachment_image() segítségével jelenítse meg a képet, és mutasson helyőrző SVG-t, ha nincs kiválasztott kép:

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>

Az blockstudio_placeholder_dark() olyan beágyazott SVG-t ad vissza, amely az currentColor elemet használja az --color-accent változóval, így automatikusan alkalmazkodik a témához. Világos témához használja ezt: blockstudio_placeholder_light(). Mindkettő elfogad egy változatot megadó argumentumot:

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

Oldalak összeállítása

Az oldalakon a <block> szintaxissal állíthat össze teljes elrendezéseket a blokkokból. Hozzon létre egy kezdőlapot:

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>

Ennyi az egész. Minden <block> elem beilleszti a blokkot az alapértelmezett attribútumértékeivel. Futtassa ezt: wp bs pages sync, hogy az oldal forrását alkalmazza erre: WordPress.

Ha egy adott oldalnál felül szeretné írni az alapértékeket, közvetlenül adja meg az attribútumokat:

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

Ha az templateLock értéke "all", az ügyfelek nem adhatnak hozzá, nem távolíthatnak el és nem rendezhetnek át blokkokat. Az oldalszerkezetet a sablon rögzíti. A többi zárolási módról és szerkesztési vezérlőről a Pages oldalon olvashat.

Bővítés

Egy minimális könyvtár 3-5 blokkal indul. Egy átfogó könyvtárban 8-14 blokk van. Íme a gyakori blokktípusok, nagyjából előfordulásuk gyakorisága szerinti sorrendben:

Blokk Leírás Fő mezők
Hero Nagy címsor CTA-kkal címsor, leírás, hivatkozások
Funkciók Előnyök rácsos elrendezésben címsor, ismétlő címmel és leírással
CTA Cselekvésre ösztönző banner címsor, leírás, hivatkozás
Árazás Csomagok összehasonlítása címsor, ismétlő névvel, árral és funkciókkal
Vélemények Ügyfélidézetek ismétlő idézettel, névvel és szerepkörrel
GYIK Kérdések harmonikaszerű listája címsor, ismétlő kérdéssel és válasszal
Logók Ügyfelek logóinak felhője címsor (a logók jellemzően rögzített SVG-k)
Tartalom Váltakozó szöveg- és képsorok ismétlő címsorral, leírással és képpel
Bemutató Teljes szélességű kép felirattal címsor, leírás, kép
Csapat Csapattagok rácsos elrendezésben címsor, ismétlő névvel, szerepkörrel és képpel
Statisztikák Fő mérőszámok ismétlő számmal és címkével

Minden blokk ugyanazt a mintát követi: fülek (Tartalom + Szekció), csoportok a rendszerezéshez, ismétlők a listákhoz és a szekció-segédfüggvény az egységes térközökhöz. Miután elkészített két-három blokkot, a továbbiak hozzáadása már rutinfeladat.

További oldalak hozzáadása

Ahogy bővül a könyvtára, állítson össze különböző oldalakat ugyanazokból a blokkokból:

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>

Ugyanazok a blokkok több oldalt is kiszolgálnak, mindegyiket eltérő alapértékekkel. Ez a könyvtáras megközelítés előnye: építse meg egyszer a blokkokat, és állítsa össze belőlük annyi oldalt, amennyire szüksége van.

Következő lépések