İçeriğe geç

Blok kitaplığı oluşturma

Blok kitaplığı, tam sayfalar oluşturmak üzere bir araya gelen, kendi içinde tamamlanmış bölüm blokları kümesidir. Her blok kendi şemasına, şablonuna ve stillerine sahiptir. Blockstudio; Tailwind CSS işleme, öznitelik kaydı ve sayfa eşitleme için çerçeveyi sağlar. Blokları siz sağlarsınız.

Bu kılavuz, yüzlerce üretim temasında kullanılan aynı mimariyi izleyerek sıfırdan bir kitaplık oluşturmayı anlatır. Kılavuzun sonunda bir hero bölümü, özellikler ızgarası ve birleştirilmiş bir ana sayfası olan çalışan bir temanız olacak.

Klasör Yapısı

Her Blockstudio teması aynı düzeni izler:

Kod
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

Bloklar blockstudio/sections/ içinde bulunur. Her blok, block.json şemasına ve index.php şablonuna sahip bir klasördür. Sayfalar pages/ içinde bulunur ve blokları <block> söz dizimini kullanarak birleştirir.

Temel dosyalar

blockstudio.json

Bu dosya, Blockstudio’ın temanızı nasıl işleyeceğini yapılandırır. Yapılandırma her tema için aynıdır:

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 varsayılan WordPress blok stillerini kaldırır. fullWidth, page yazı türlerinin tam genişliğe yayılmasını sağlar. canvas daha sade bir düzenleme deneyimi için düzenleyici tuvali modunu etkinleştirir.

tailwind.config alanı bilerek boş bırakılmıştır. Tailwind v4 ile tüm yapılandırma, CSS öncelikli yaklaşım kullanılarak style.css içinde bulunur.

index.php

Ana WordPress şablonu. Bu standart WordPress’dır; Blockstudio’a özgü bir şey içermez:

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>

Gezinmeye ihtiyaç duyduğunuzda bir header.php ve footer.php ekleyin. Şimdilik blokları oluşturmak için basit bir şablon yeterlidir.

Tasarım belirteçleri

Tüm tema düzenlemeleri, Tailwind v4’ın @theme yönergesi kullanılarak style.css içinde yapılır. Tasarım sisteminizin özü budur.

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

Her temanın en azından şunlara ihtiyacı vardır:

Belirteç Amaç
--font-sans veya --font-serif Birincil yazı tipi
--color-bg Sayfa arka planı
--color-elevated Kart/yüzey arka planı
--color-subtle Kenarlıklar, ayırıcılar
--color-muted İkincil metin
--color-accent Birincil marka rengi

Bu belirteçler, Tailwind yardımcı sınıflarını otomatik olarak oluşturur. --color-accent, bg-accent, text-accent, border-accent ve benzerlerine dönüşür.

Açık renkli bir tema için değerleri tersine çevirin:

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

Temel stiller ve yardımcı sınıflar

@theme bloğunun altına gövde stillerini, temel katman varsayılanlarını ve özel yardımcı sınıfları ekleyin.

Gövde stilleri @layer dışında olmalıdır; böylece WordPress düzenleyicisi bunları alır:

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

Temel katman, öğe varsayılanları içindir:

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

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

	p {
		text-wrap: pretty;
	}
}

Özel yardımcı sınıflar, yeniden kullanılabilir kalıplar içindir. Her tema tutarlı bölüm aralıkları için bir container yardımcı sınıfı, ayrıca genellikle card, badge ve düğme yardımcı sınıfları tanımlar:

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

Sözde seçicileri @utility bloğunun içinde, CSS iç içe yerleştirmeyi (&:hover) kullanarak yazın. Bunları hiçbir zaman yardımcı sınıf adına koymayın. @utility btn-primary:hover {} geçersizdir ve Tailwind tarafından reddedilir.

@source satır içi

Blockstudio, blok şablonlarınızı tarayarak Tailwind sınıflarını otomatik olarak bulur. Ancak blok şablonlarının dışındaki (functions.php, header.php, index.php içindeki) sınıflar taranmaz. Bunları @source inline ile bildirin:

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

Bu, Tailwind’a, taranmayan PHP dosyalarında bulunsalar bile bu sınıfları çıktıya eklemesini söyler.

Bölüm kalıbı

Bölüm kalıbı, bir Blockstudio blok kitaplığındaki en önemli kuraldır. İki ortak mekanizma, özel bir alan ve bir PHP yardımcı işlevi aracılığıyla tüm bloklara tutarlı aralıklar, arka plan değiştirme ve dolgu denetimi sağlar.

Bölüm alanı

Her bloğun başvurabileceği ortak bir alan tanımı oluşturun:

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

Bu alan, her bloğun denetçisinde “Bölüm” sekmesinin altında görünür. Müşteriler iki denetim kullanabilir: vurgu arka planını açıp kapatmak ve alt dolguyu kaldırmak (bölümleri boşluk olmadan üst üste eklemek için kullanışlıdır).

Bölüm yardımcı işlevi

functions.php içinde bu öznitelikleri CSS sınıflarına dönüştüren bir yardımcı işlev oluşturun:

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

Her blok şablonu bu yardımcı işlevi ilk satırında çağırır. Yardımcı işlev iki sınıf dizesi döndürür: biri dış <section> öğesi, diğeri iç <div> kapsayıcısı için.

Tailwind yapılandırma filtresi

Ayrıca functions.php içinde, style.css öğenizi Blockstudio’ın Tailwind işleyicisine aktaran filtreyi ekleyin:

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

Bu, Blockstudio’a style.css öğenizi Tailwind v4 yapılandırma kaynağı olarak kullanmasını söyler. Bu olmadan @theme belirteçleriniz ve @utility tanımlarınız blok şablonlarında kullanılamaz.

İlk bloğunuz: Hero

Bir hero bölümü, blok kalıbının tamamını gösterir. Önce şemayla başlayın:

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

Dikkat edilmesi gereken temel kalıplar:

tabs sarmalayıcısı, iki sekmeli bir denetçi oluşturur: bloğun alanları için “İçerik”, ortak bölüm denetimleri için “Bölüm”. Her blok bu yapıyı kullanır.

Alanlar group kapsayıcıları içinde düzenlenir. Gruplar, denetçide ilişkili alanları görsel olarak ayırır. İlk grupta metin alanları, ikinci grupta bağlantı alanları bulunur.

Varsayılan değerler, blok eklendiği anda eksiksiz görünmesi için anlamlı içerik sağlar. Kullanıcı etkileşimi olmadan blok eklenen sayfa düzeninde bu kritik önem taşır.

Şimdi şablon:

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>

Şablon tutarlı bir kalıp izler:

  1. CSS sınıflarını almak için bölüm yardımcı işlevini çağırın
  2. useBlockProps ve bölüm sınıflarını içeren dış <section>
  3. Kapsayıcı sınıflarını içeren iç <div>
  4. $a‘ten oluşturulan içerik (öznitelik kısaltması)
  5. İsteğe bağlı alanlar için koşullu oluşturma
  6. Uygun kaçışlama: metin için esc_html(), URL’ler için esc_url(), öznitelikler için esc_attr()

Yineleyiciler ekleme: Özellikler ızgarası

Yineleyiciler, müşterilerin öğe eklemesine, kaldırmasına ve sıralamasını değiştirmesine olanak tanır. Özellikler ızgarası klasik örnektir:

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

textMinimized özelliği, yineleyici satırı daraltıldığında hangi metnin gösterileceğini belirler. title alan değerini okur; alan boşsa “Özellik” metnini kullanır. Bu sayede çok sayıda öğe olduğunda denetçi kullanılabilir kalır.

default dizisi başlangıç öğelerini sağlar. Bunlar blok ilk eklendiğinde görünür. Bloğun hemen eksiksiz görünmesi için her zaman gerçekçi varsayılanlar sağlayı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>

Yineleyici öğelerine basit bir PHP dizisi olarak erişilir. foreach ile döngü kurun ve her öğenin alanlarına kendi id değerleriyle erişin.

Görseller ve yer tutucular

Görsel içeren bloklarda files alan türünü ve MediaPlaceholder bileşenini kullanın. Yer tutucu, düzenleyicide sürükle-bırak alanı gösterir:

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

Şablonda görseli wp_get_attachment_image() ile oluşturun ve görsel seçilmemişse yer tutucu SVG’sini gösterin:

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(), temanızın renklerine otomatik uyum sağlaması için --color-accent değişkeniyle currentColor kullanan satır içi bir SVG döndürür. Açık renkli temalar için blockstudio_placeholder_light() kullanın. Her ikisi de bir varyant bağımsız değişkeni kabul eder:

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

Sayfaları birleştirme

Sayfalar, <block> söz dizimini kullanarak blokları tam düzenlere dönüştürür. Bir ana sayfa oluşturun:

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>

Hepsi bu kadar. Her <block> öğesi, bloğu varsayılan öznitelik değerleriyle ekler. Sayfa kaynağını WordPress’a uygulamak için wp bs pages sync komutunu çalıştırın.

Belirli bir sayfanın varsayılanlarını geçersiz kılmak için öznitelikleri doğrudan iletin:

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

templateLock değeri "all" olarak ayarlandığında müşteriler blok ekleyemez, kaldıramaz veya blokların sırasını değiştiremez. Sayfa yapısı şablonunuza kilitlenir. Diğer kilitleme modları ve düzenleme denetimleri için Sayfalar bölümüne bakın.

Ölçeği büyütme

Basit bir kitaplık 3-5 blokla başlar. Kapsamlı bir kitaplıkta 8-14 blok bulunur. Sık kullanılan blok türleri, yaklaşık olarak kullanım sıklığına göre sıralanmıştır:

Blok Açıklama Temel alanlar
Hero Büyük başlık ve harekete geçirici öğeler başlık, açıklama, bağlantılar
Özellikler Avantajlar ızgarası başlık, başlık + açıklama içeren yineleyici
CTA Harekete geçirici banner başlık, açıklama, bağlantı
Fiyatlandırma Plan karşılaştırması başlık, ad + fiyat + özellikler içeren yineleyici
Müşteri yorumları Müşteri alıntıları alıntı + ad + rol içeren yineleyici
SSS Soru akordeonu başlık, soru + yanıt içeren yineleyici
Logolar Müşteri logoları koleksiyonu başlık (logolar genellikle sabit kodlanmış SVG’lerdir)
İçerik Dönüşümlü metin + görsel satırları başlık + açıklama + görsel içeren yineleyici
Vitrin Açıklamalı tam genişlikte görsel başlık, açıklama, görsel
Ekip Ekip üyesi ızgarası başlık, ad + rol + görsel içeren yineleyici
İstatistikler Temel ölçümler sayı + etiket içeren yineleyici

Her blok aynı kalıbı izler: sekmeler (İçerik + Bölüm), düzenleme için gruplar, listeler için yineleyiciler ve tutarlı aralıklar için bölüm yardımcı işlevi. İki ya da üç blok oluşturduktan sonra yenilerini eklemek mekanik bir işe dönüşür.

Daha fazla sayfa ekleme

Kitaplığınız büyüdükçe aynı bloklardan farklı sayfalar oluşturun:

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>

Aynı bloklar, her biri farklı varsayılanlarla birden çok sayfaya hizmet eder. Kitaplık yaklaşımının gücü budur: blokları bir kez oluşturun, ardından ihtiyaç duyduğunuz kadar sayfada birleştirin.

Sonraki Adımlar