Özel Alanlar
Özel alanlar, birden fazla blokta kullanılabilen yeniden kullanılabilir alan grupları tanımlamanızı sağlar. Bunları alan şablonları olarak düşünebilirsiniz: bir kez tanımlayın, her yerde kullanın.
Özel alanlar, özel alan türleri ile aynı değildir. Mevcut alan gruplarını yeniden kullanmak için custom/{name} kullanın. Bir tema veya eklenti yeni bir düzenleyici kontrolü ve değer yapısı kaydettiğinde, acme/dimensions gibi ad alanlı bir özel alan türü kullanın.
Dosya Sistemi Kaydı
Blokstudio dizininizdeki fields/ dizininin içinde bir field.json dosyası oluşturun:
theme/
└── blockstudio/
└── fields/
└── hero/
└── field.json
{
"$schema": "https://blockstudio.dev/schema/field",
"name": "hero",
"title": "Hero Section",
"attributes": [
{
"id": "heading",
"type": "text",
"label": "Heading",
"default": "Hello World"
},
{ "id": "description", "type": "textarea", "label": "Description" },
{ "id": "enabled", "type": "toggle", "label": "Enabled" }
]
}
PHP Filtresiyle Kayıt
blockstudio/fields filtresini kullanarak özel alanları programlı olarak kaydedin:
add_filter('blockstudio/fields', function ($fields) {
$fields['cta'] = [
'title' => 'Call to Action',
'attributes' => [
['id' => 'text', 'type' => 'text', 'label' => 'Button Text'],
['id' => 'url', 'type' => 'text', 'label' => 'URL'],
],
];
return $fields;
});
block.json Kullanımı
custom/{name} türünü kullanarak bir özel alana başvurun:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero" }]
}
}
Bu, özel alan tanımında tanımlanan alanları satır içinde açar. Açılan alanlar özgün kimliklerini kullanır (heading, description, enabled).
Özel alanlar tam grup tanımlarını da yeniden kullanabilir:
{
"name": "section-header",
"attributes": [
{
"id": "section-header",
"type": "group",
"title": "Header",
"attributes": [
{ "id": "kicker", "type": "text", "label": "Kicker" },
{ "id": "title", "type": "text", "label": "Title" }
]
}
]
}
{
"blockstudio": {
"attributes": [{ "type": "custom/section-header" }]
}
}
Grup alt öğeleri section-header_kicker, section-header_title vb. olarak depolanır. Şablonlarda, bunları temiz bir grup nesnesine çıkarmak için bs_get_group() kullanın.
Kimlik Yapısı
Alan kimliklerine ön ek eklemek veya onları dönüştürmek için idStructure kullanın. {id} yer tutucusu özgün alan kimliğiyle değiştirilir:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
}
Bu işlem şu kimliklere sahip alanlar oluşturur: hero_heading, hero_description, hero_enabled.
Geçersiz Kılmalar
overrides kullanarak örneğe özel alanları özelleştirin. Anahtarlar, tanımdaki özgün alan kimlikleridir:
{
"blockstudio": {
"attributes": [
{
"type": "custom/hero",
"idStructure": "hero_{id}",
"overrides": {
"heading": { "default": "Welcome", "label": "Title" },
"enabled": { "id": "active" }
}
}
]
}
}
Geçersiz kılma özellikleri, özgün alan tanımının üzerine birleştirilir. Bir id geçersiz kılması, idStructure kalıbını atlar. Yukarıdaki örnekte enabled, hero_enabled yerine active olur.
Birleştirme yalnızca bir düzey derinliğindedir: üzerine yazdığınız bir özellik, özgün özelliğin tamamının yerini alır. Bir options geçersiz kılması, seçenek listesine ekleme değil, seçenek listesinin tamamıdır; aynı durum conditions ve bir grubun attributes için de geçerlidir. Referanstaki koşullar sonradan yine eklenir.
{
"type": "custom/background",
"overrides": {
"background": {
"options": [
{ "value": "white", "label": "White" },
{ "value": "grey", "label": "Grey" }
]
}
}
}
Bu blok, tanımda kaç seçenek listelenirse listelensin yalnızca White ve Grey seçeneklerini sunar.
Koşullar
Özel alan tanımlarındaki koşullar, idStructure uygulandığında otomatik olarak yeniden yazılır. Bir kardeş alana koşullu olarak bağlı alan, açıldıktan sonra da çalışmaya devam eder.
{
"name": "font-size",
"attributes": [
{ "id": "enable", "type": "toggle", "label": "Modify font size" },
{
"id": "min",
"type": "number",
"label": "Min Size",
"conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
},
{
"id": "max",
"type": "number",
"label": "Max Size",
"conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
}
]
}
{ "type": "custom/font-size", "idStructure": "title_font_{id}" }
Blockstudio bunu title_font_enable, title_font_min, title_font_max olarak açar ve koşulları enable yerine title_font_enable öğesine başvuracak şekilde yeniden yazar. Geçiş kontrolleri, alanlar satır içinde tanımlanmış gibi çalışır.
Başvuru düzeyindeki koşullar
Her açılan alana uygulamak için başvuruya conditions ekleyin. Bu, tüm grubu harici bir geçişin arkasında gizlemek için kullanışlıdır:
{
"type": "custom/font-size",
"idStructure": "subtitle_font_{id}",
"conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}
Bu koşullar, alan tanımında zaten belirlenmiş olan koşullarla birleştirilir. Koşul kimlikleri de idStructure aracılığıyla yeniden yazılır.
Birden Fazla Özel Alan
Tek bir blokta normal alanların yanı sıra birden fazla özel alan kullanabilirsiniz:
{
"blockstudio": {
"attributes": [
{ "id": "intro", "type": "text", "label": "Intro" },
{ "type": "custom/hero", "idStructure": "hero_{id}" },
{ "type": "custom/cta", "idStructure": "cta_{id}" }
]
}
}
İç İçe Kullanım
Özel alanlar gruplar, sekmeler ve tekrarlayıcıların içinde çalışır:
{
"blockstudio": {
"attributes": [
{
"type": "group",
"id": "content",
"title": "Content",
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
]
}
}
Ek Keşif Yolları
Alan keşfi için ek dizinler eklemek üzere blockstudio/fields/paths filtresini kullanın:
add_filter('blockstudio/fields/paths', function ($paths) {
$paths[] = get_stylesheet_directory() . '/blockstudio/fields';
return $paths;
});
Statik Analiz
blockstudio/phpstan paketi, PHP, Twig, Blade, blok etiketleri ve çıkarılan nitelik yapılarını doğrularken, dosya destekli custom/* başvurularını genişletir. Genişletme işlemi yukarıda açıklanan aynı iç içe yerleştirme, idStructure ve overrides kurallarını izler.
Analiz edilen projenin dışındaki tanımlar için kütüphane dizinini phpstan.neon içindeki blockstudioScanRoots öğesine ekleyin. Yalnızca blockstudio/fields PHP filtresiyle kaydedilen alanlar çalışma zamanında bulunur ve statik olarak çıkarılamaz.