İçeriğe geç

Ö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:

Kod
theme/
└── blockstudio/
    └── fields/
        └── hero/
            └── field.json
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:

PHP
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:

JSON
{
  "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:

JSON
{
  "name": "section-header",
  "attributes": [
    {
      "id": "section-header",
      "type": "group",
      "title": "Header",
      "attributes": [
        { "id": "kicker", "type": "text", "label": "Kicker" },
        { "id": "title", "type": "text", "label": "Title" }
      ]
    }
  ]
}
JSON
{
  "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:

JSON
{
  "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:

JSON
{
  "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.

JSON
{
  "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.

JSON
{
  "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 }]]
    }
  ]
}
JSON
{ "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:

JSON
{
  "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:

JSON
{
  "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:

JSON
{
  "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:

PHP
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.