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:
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:
{
"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:
<!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.
/*
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:
@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:
body {
@apply bg-bg font-sans text-white antialiased;
}
Temel katman, öğe varsayılanları içindir:
@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:
@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:
@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:
{
"$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
/**
* 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:
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:
{
"$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 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:
- CSS sınıflarını almak için bölüm yardımcı işlevini çağırın
useBlockPropsve bölüm sınıflarını içeren dış<section>- Kapsayıcı sınıflarını içeren iç
<div> $a‘ten oluşturulan içerik (öznitelik kısaltması)- İsteğe bağlı alanlar için koşullu oluşturma
- Uygun kaçışlama: metin için
esc_html(), URL’ler içinesc_url(), öznitelikler içinesc_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:
{
"$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 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:
{
"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:
<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:
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:
{
"name": "home",
"title": "Home",
"slug": "home",
"postType": "page",
"postStatus": "publish",
"templateLock": "all"
}
<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:
<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:
<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>
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
- Öznitelikleri kaydetme: alan türleri ve özelliklerinin kapsamlı başvurusu
- Alan türleri: kullanılabilir tüm alan türleri
- Alan kalıpları yemek kitabı: koşullu gruplar, akıllı seçimler ve yineleyici tarifleri
- Sayfalar: şablon kilitleme, düzenleme modları ve anahtarlı birleştirme
- Dosya tabanlı sayfalar oluşturma: sayfa şablonları ve eşitleme için uygulamalı anlatım
- Etkileşim: bloklara istemci tarafı davranışı ekleme