İçeriğe geç

Blok Bağlamı ve İletişim

Çoğu blok kendi başına yeterlidir. Kendi alanları ve şablonları vardır; çevrelerinde ne olduğuyla ilgilenmezler. Ancak bazı bileşenler doğal olarak hiyerarşiktir: sütun sayısını ve aralığı üst bloğun denetlediği bir kart ızgarası, para birimini üst bloğun belirlediği bir fiyatlandırma tablosu ya da alt bloklarına açık veya koyu tema kullanmalarını söyleyen bir bölüm sarmalayıcısı.

WordPress bunun için bir blok bağlamı API sağlar. Üst blok verilerinden bazılarını sunar, alt bloklar da bu verilere abone olur. Üst blok değiştiğinde alt bloklar otomatik olarak güncellenir. Blockstudio bu işi önemli ölçüde kolaylaştırır: providesContext yapılandırmanız gerekmez. Her Blockstudio bloğu tüm özniteliklerini otomatik olarak bağlam olarak sunar. Alt blokların abone olmak için block.json dosyalarına tek satır eklemesi yeterlidir.

Bu kılavuzda bağlam kullanan, her biri farklı bir iletişim gereksinimini gösteren dört gerçek dünya bileşen kalıbı oluşturuluyor.

Blockstudio’da Bağlam Nasıl Çalışır

Standart WordPress kullanımında her üst özniteliği providesContext içinde bir bağlam anahtarına açıkça eşlemeniz, ardından bu anahtarları alt bloğun usesContext listesine eklemeniz gerekir. Blockstudio ilk adımı tamamen ortadan kaldırır.

Üst blok: Yapılandırma gerekmez. Her Blockstudio bloğu tüm özniteliklerini blok adı altında otomatik olarak sunar.

Alt blok: Üst bloğun adını kullanarak usesContext ekleyin:

JSON
{
  "usesContext": ["my-theme/parent-block"]
}

Alt şablon: Üst özniteliklere $context (veya kısa biçimi $c) aracılığıyla erişin:

PHP
<?php $parent = $context['my-theme/parent-block']; ?>
<p>Parent says: <?php echo esc_html( $parent['message'] ); ?></p>

Kurulumun tamamı bundan ibaret. Üst blokta providesContext, öznitelik eşlemesi veya kayıt kodu gerekmez. Alt blok, üst bloğun dönüştürülmüş tüm özniteliklerini alır; böylece medya alanları ek verilerine çözümlenir, seçim alanları returnFormat kurallarına uyar ve tekrarlayıcılar tamamen genişletilir.

İki tür bağlam

Blockstudio şablonlarda farklı amaçlara hizmet eden iki bağlam değişkeni sağlar:

Değişken İçerik Kullanım amacı
$context / $c Üst blok öznitelikleri (usesContext aracılığıyla) Bileşenler arası iletişim
$block['context'] / $b['context'] WordPress döngü verileri (postId, postType) Sorgu bloğu döngüleri

İlki, blokların üst bloklarıyla iletişim kurmasını sağlar. İkincisi, hangi gönderiyi oluşturduklarını bilmeleri gereken Sorgu döngüsündeki bloklar içindir. Bu kılavuz ilk türe odaklanır.

Düzenleyici desteği

Düzenleyicide bağlam güncellemeleri reaktiftir. Kullanıcı bir üst bloğun alan değerini değiştirdiğinde, bu üst bloğun bağlamına abone olan tüm alt bloklar yeni değerle otomatik olarak yeniden oluşturulur. Elle yenileme gerekmez.

Bölüm Sarmalayıcısı

En yaygın bağlam kalıbı, alt bloklarına tema ayarları sağlayan bir sarmalayıcı bloktur. Üst blokta arka plan rengi, metin rengi ve dolgu alanları bulunur. Alt bloklar tutarlı biçimde stillendirilmek için bu değerleri okur.

Üst: Bölüm

JSON
{
  "name": "my-theme/section",
  "title": "Section",
  "category": "design",
  "icon": "align-wide",
  "description": "Section wrapper with theme settings.",
  "blockstudio": {
    "attributes": [
      {
        "id": "theme",
        "type": "select",
        "label": "Theme",
        "default": "light",
        "options": [
          { "value": "light", "label": "Light" },
          { "value": "dark", "label": "Dark" },
          { "value": "accent", "label": "Accent" }
        ]
      },
      {
        "id": "spacing",
        "type": "select",
        "label": "Spacing",
        "default": "md",
        "options": [
          { "value": "sm", "label": "Small" },
          { "value": "md", "label": "Medium" },
          { "value": "lg", "label": "Large" }
        ]
      }
    ]
  }
}
PHP
<?php
$theme_classes = array(
	'light'  => 'bg-white text-gray-900',
	'dark'   => 'bg-gray-900 text-white',
	'accent' => 'bg-indigo-600 text-white',
);
$spacing_classes = array(
	'sm' => 'py-8',
	'md' => 'py-16',
	'lg' => 'py-24',
);
$classes = ( $theme_classes[ $a['theme'] ] ?? '' ) . ' ' . ( $spacing_classes[ $a['spacing'] ] ?? '' );
?>
<div useBlockProps class="<?php echo esc_attr( $classes ); ?>">
  <InnerBlocks
    allowedBlocks='<?php echo esc_attr( wp_json_encode( array( 'my-theme/section-heading', 'my-theme/section-text', 'core/columns', 'core/group' ) ) ); ?>'
  />
</div>

Alt: Bölüm Başlığı

JSON
{
  "name": "my-theme/section-heading",
  "title": "Section Heading",
  "category": "design",
  "icon": "heading",
  "description": "Heading that adapts to section theme.",
  "usesContext": ["my-theme/section"],
  "parent": ["my-theme/section"],
  "blockstudio": {
    "attributes": [
      { "id": "text", "type": "text", "label": "Heading", "default": "Section Title" },
      {
        "id": "size",
        "type": "select",
        "label": "Size",
        "default": "lg",
        "options": [
          { "value": "sm", "label": "Small" },
          { "value": "lg", "label": "Large" },
          { "value": "xl", "label": "Extra Large" }
        ]
      }
    ]
  }
}
PHP
<?php
$section = $context['my-theme/section'] ?? array();
$theme   = $section['theme'] ?? 'light';

$color_class = match ( $theme ) {
	'light'  => 'text-gray-900',
	'dark'   => 'text-white',
	'accent' => 'text-white',
	default  => 'text-gray-900',
};

$size_class = match ( $a['size'] ) {
	'sm' => 'text-2xl',
	'lg' => 'text-4xl',
	'xl' => 'text-6xl',
	default => 'text-4xl',
};
?>
<h2 useBlockProps class="<?php echo esc_attr( "$color_class $size_class font-bold" ); ?>">
  <?php echo esc_html( $a['text'] ); ?>
</h2>

Gösterdiği: Başlığın kendine ait bir renk alanı yoktur. Bağlamdan bölümün theme değerini okur ve görünümünü uyarlar. Kullanıcı düzenleyicide bölüm temasını “Light” yerine “Dark” yaptığında başlık metninin rengi hemen güncellenir.

Alt bloğun block.json içindeki parent özelliği, bloğun eklenebileceği yerleri sınırlar. Blok, ekleyici içinde yalnızca kullanıcı bir my-theme/section bloğunun içindeyken görünür. Bu isteğe bağlıdır ancak yalnızca belirli bir üst bloğun içinde anlamlı olan bloklar için önerilir.

Alt: Bölüm Metni

JSON
{
  "name": "my-theme/section-text",
  "title": "Section Text",
  "category": "design",
  "icon": "text",
  "description": "Body text that adapts to section theme.",
  "usesContext": ["my-theme/section"],
  "parent": ["my-theme/section"],
  "blockstudio": {
    "attributes": [
      { "id": "text", "type": "textarea", "label": "Text", "default": "Section body text." }
    ]
  }
}
PHP
<?php
$section = $context['my-theme/section'] ?? array();
$theme   = $section['theme'] ?? 'light';

$color_class = match ( $theme ) {
	'dark', 'accent' => 'text-white/80',
	default          => 'text-gray-600',
};
?>
<p useBlockProps class="<?php echo esc_attr( "$color_class text-lg leading-relaxed" ); ?>">
  <?php echo esc_html( $a['text'] ); ?>
</p>

Artık hem başlık hem de metin bölümün temasına uyum sağlar. Kullanıcı temayı üst blokta bir kez seçer, tüm alt bloklar da uyum sağlar.

Kart Izgarası

Kart alt bloklarının düzen ayarlarını denetleyen bir ızgara üst bloğu. Üst blok sütunları ve aralığı belirler. Alt bloklar bu değerleri kullanarak düzen bağlamını anlar ve stillerini buna göre ayarlar.

Üst: Kart Izgarası

JSON
{
  "name": "my-theme/card-grid",
  "title": "Card Grid",
  "category": "design",
  "icon": "grid-view",
  "description": "Responsive card grid with configurable columns.",
  "blockstudio": {
    "attributes": [
      {
        "id": "columns",
        "type": "range",
        "label": "Columns",
        "default": 3,
        "min": 1,
        "max": 4,
        "step": 1
      },
      {
        "id": "gap",
        "type": "select",
        "label": "Gap",
        "default": "md",
        "options": [
          { "value": "sm", "label": "Small" },
          { "value": "md", "label": "Medium" },
          { "value": "lg", "label": "Large" }
        ]
      },
      {
        "id": "cardStyle",
        "type": "select",
        "label": "Card Style",
        "default": "elevated",
        "options": [
          { "value": "elevated", "label": "Elevated (shadow)" },
          { "value": "outlined", "label": "Outlined (border)" },
          { "value": "flat", "label": "Flat (no decoration)" }
        ]
      }
    ]
  }
}
PHP
<?php
$gap_class = match ( $a['gap'] ) {
	'sm' => 'gap-4',
	'md' => 'gap-6',
	'lg' => 'gap-8',
	default => 'gap-6',
};
?>
<div useBlockProps class="grid grid-cols-<?php echo esc_attr( $a['columns'] ); ?> <?php echo esc_attr( $gap_class ); ?>">
  <InnerBlocks
    allowedBlocks='<?php echo esc_attr( wp_json_encode( array( 'my-theme/card' ) ) ); ?>'
    template='<?php echo esc_attr( wp_json_encode( array(
      array( 'my-theme/card', array() ),
      array( 'my-theme/card', array() ),
      array( 'my-theme/card', array() ),
    ) ) ); ?>'
  />
</div>

Alt: Kart

JSON
{
  "name": "my-theme/card",
  "title": "Card",
  "category": "design",
  "icon": "cover-image",
  "description": "Card that inherits style from its grid parent.",
  "usesContext": ["my-theme/card-grid"],
  "parent": ["my-theme/card-grid"],
  "blockstudio": {
    "attributes": [
      { "id": "image", "type": "files", "label": "Image", "multiple": false },
      { "id": "title", "type": "text", "label": "Title", "default": "Card Title" },
      { "id": "description", "type": "textarea", "label": "Description", "default": "Card description goes here." },
      { "id": "url", "type": "link", "label": "Link" }
    ]
  }
}
PHP
<?php
$grid      = $context['my-theme/card-grid'] ?? array();
$card_style = $grid['cardStyle'] ?? 'elevated';

$style_class = match ( $card_style ) {
	'elevated' => 'bg-white rounded-xl shadow-md',
	'outlined' => 'bg-white rounded-xl border border-gray-200',
	'flat'     => 'bg-gray-50 rounded-xl',
	default    => 'bg-white rounded-xl shadow-md',
};
?>
<div useBlockProps class="<?php echo esc_attr( "$style_class overflow-hidden" ); ?>">
  <?php if ( $a['image'] ) : ?>
    <img
      src="<?php echo esc_url( $a['image']['url'] ); ?>"
      alt="<?php echo esc_attr( $a['image']['alt'] ); ?>"
      class="w-full aspect-video object-cover" />
  <?php endif; ?>
  <div class="p-6">
    <h3 class="text-lg font-semibold"><?php echo esc_html( $a['title'] ); ?></h3>
    <p class="mt-2 text-gray-600"><?php echo esc_html( $a['description'] ); ?></p>
    <?php if ( $a['url'] ) : ?>
      <a href="<?php echo esc_url( $a['url']['url'] ); ?>" class="mt-4 inline-block text-indigo-600 font-medium">
        <?php echo esc_html( $a['url']['title'] ?: 'Learn more' ); ?>
      </a>
    <?php endif; ?>
  </div>
</div>

Gösterdiği: Kartın kendine ait bir stil alanı yoktur. Izgara üst bloğundan cardStyle değerini okur. Kullanıcı ızgara stilini “Elevated” yerine “Outlined” yaptığında ızgaradaki tüm kartlar aynı anda güncellenir. Böylece kullanıcı her kartı tek tek güncellemek zorunda kalmadan kartların görsel tutarlılığı korunur.

<InnerBlocks> üzerindeki template özniteliği, ızgarayı üç kartla doldurarak kullanıcıya bir başlangıç noktası sunar.

Fiyatlandırma Tablosu

Üst bloğun, alt blokların gösteriminde kullandığı ortak iş mantığını (para birimi, faturalandırma dönemi) sağladığı daha gelişmiş bir kalıp. Böylece aynı alanların her fiyatlandırma katmanında tekrarlanması önlenir.

Üst: Fiyatlandırma Tablosu

JSON
{
  "name": "my-theme/pricing-table",
  "title": "Pricing Table",
  "category": "text",
  "icon": "money-alt",
  "description": "Pricing comparison with shared currency and billing settings.",
  "blockstudio": {
    "attributes": [
      {
        "id": "currency",
        "type": "select",
        "label": "Currency",
        "default": "usd",
        "options": [
          { "value": "usd", "label": "USD ($)" },
          { "value": "eur", "label": "EUR (\u20ac)" },
          { "value": "gbp", "label": "GBP (\u00a3)" }
        ]
      },
      {
        "id": "period",
        "type": "select",
        "label": "Billing Period",
        "default": "month",
        "options": [
          { "value": "month", "label": "Monthly" },
          { "value": "year", "label": "Yearly" }
        ]
      }
    ]
  }
}
PHP
<div useBlockProps class="grid grid-cols-3 gap-6 items-start">
  <InnerBlocks
    allowedBlocks='<?php echo esc_attr( wp_json_encode( array( 'my-theme/pricing-tier' ) ) ); ?>'
    template='<?php echo esc_attr( wp_json_encode( array(
      array( 'my-theme/pricing-tier', array( 'name' => 'Starter', 'price' => 9 ) ),
      array( 'my-theme/pricing-tier', array( 'name' => 'Pro', 'price' => 29, 'highlighted' => true ) ),
      array( 'my-theme/pricing-tier', array( 'name' => 'Enterprise', 'price' => 99 ) ),
    ) ) ); ?>'
  />
</div>

Alt: Fiyatlandırma Katmanı

JSON
{
  "name": "my-theme/pricing-tier",
  "title": "Pricing Tier",
  "category": "text",
  "icon": "tag",
  "description": "Single pricing tier that reads currency from parent.",
  "usesContext": ["my-theme/pricing-table"],
  "parent": ["my-theme/pricing-table"],
  "blockstudio": {
    "attributes": [
      { "id": "name", "type": "text", "label": "Tier Name", "default": "Plan" },
      { "id": "price", "type": "number", "label": "Price", "default": 0 },
      { "id": "highlighted", "type": "toggle", "label": "Highlighted", "default": false },
      {
        "id": "features",
        "type": "repeater",
        "label": "Features",
        "attributes": [
          { "id": "text", "type": "text", "label": "Feature" }
        ]
      }
    ]
  }
}
PHP
<?php
$table    = $context['my-theme/pricing-table'] ?? array();
$currency = $table['currency'] ?? 'usd';
$period   = $table['period'] ?? 'month';

$symbols = array(
	'usd' => '$',
	'eur' => "\u{20AC}",
	'gbp' => "\u{00A3}",
);
$symbol = $symbols[ $currency ] ?? '$';

$period_label = $period === 'year' ? '/year' : '/month';

$border_class = $a['highlighted'] ? 'border-2 border-indigo-600' : 'border border-gray-200';
?>
<div useBlockProps class="<?php echo esc_attr( "rounded-xl p-8 $border_class" ); ?>">
  <h3 class="text-lg font-semibold"><?php echo esc_html( $a['name'] ); ?></h3>
  <div class="mt-4">
    <span class="text-4xl font-bold"><?php echo esc_html( $symbol . $a['price'] ); ?></span>
    <span class="text-gray-500"><?php echo esc_html( $period_label ); ?></span>
  </div>
  <?php if ( ! empty( $a['features'] ) ) : ?>
    <ul class="mt-6 space-y-3">
      <?php foreach ( $a['features'] as $feature ) : ?>
        <li class="flex items-center gap-2">
          <span class="text-indigo-600">&#10003;</span>
          <?php echo esc_html( $feature['text'] ); ?>
        </li>
      <?php endforeach; ?>
    </ul>
  <?php endif; ?>
</div>

Gösterdiği: Para birimi simgesi ve faturalandırma dönemi fiyatlandırma tablosunda bir kez tanımlanır ve tüm katmanlara aktarılır. Kullanıcı USD’den EUR’ya geçtiğinde üç katmanın tümündeki para birimi simgesi aynı anda güncellenir. Bağlam olmasaydı para birimi alanını her katmanda tekrarlamanız ve değerleri elle eşitlemeniz gerekirdi.

Sorgu Döngüsü Bağlamı

WordPress, Sorgu bloğu döngülerinin içinde ayrı bir bağlam türü daha sağlar. Bir blok döngü içinde oluşturulduğunda, $block['context'] (veya $b['context']) geçerli yinelemenin gönderi verilerini içerir:

PHP
<?php
$loop_post_id   = $block['context']['postId'];
$loop_post_type = $block['context']['postType'];
?>
<article useBlockProps>
  <h2><?php echo esc_html( get_the_title( $loop_post_id ) ); ?></h2>
  <p><?php echo esc_html( get_the_excerpt( $loop_post_id ) ); ?></p>
  <a href="<?php echo esc_url( get_permalink( $loop_post_id ) ); ?>">Read more</a>
</article>

Bu, üst blok bağlamından ($context / $c) farklıdır. Döngü bağlamı WordPress çekirdeği tarafından sağlanır ve yalnızca postId ile postType içerir. Bunun için usesContext dosyanızda block.json gerekmez. Blockstudio her bloğu otomatik olarak postId ve postType‘a abone eder.

Döngü bağlamının kullanışlı olduğu yerler: Sorgu bloklarının içindeki özel gönderi kartları, gönderi üst verilerini gösteren bloklar veya döngüde gönderiye göre farklı oluşturulması gereken tüm bloklar.

Döngü bağlamından bağımsız olarak dış sayfanın gönderi verilerine de erişebilirsiniz:

PHP
$outer_post_id   = $block['postId'];   // always the current page
$loop_post_id    = $block['context']['postId'];  // current loop iteration

İç İçe Bağlam

Bağlam yalnızca tek bir düzeyde değil, tüm blok ağacında aktarılır. A bloğu B bloğunu, B de C bloğunu içeriyorsa C, A’nın bağlamına abone olabilir. Bunun nedeni WordPress’ın bağlamı InnerBlocks’ın her düzeyine aktarmasıdır.

Kod
my-theme/section (theme: "dark")
└── core/columns
    └── core/column
        └── my-theme/section-heading (reads section context)

Başlığın bölümün doğrudan alt bloğu olması gerekmez. Çekirdek blokların (sütunlar, gruplar vb.) içine iç içe yerleştirilse bile bölümün bağlamını alır. usesContext aboneliği her derinlikte çalışır.

Birden çok üst blok

Bir alt blok birden çok üst bloğa abone olabilir:

JSON
{
  "usesContext": ["my-theme/section", "my-theme/card-grid"]
}
PHP
<?php
$section = $context['my-theme/section'] ?? array();
$grid    = $context['my-theme/card-grid'] ?? array();

$theme     = $section['theme'] ?? 'light';
$cardStyle = $grid['cardStyle'] ?? 'elevated';
?>

Üst blok ata ağacında bulunamazsa anahtarı $context içinde yer almaz. Bloğun beklenen üst bloğun dışında kullanılma olasılığına karşı, bağlam değerlerini okurken her zaman null birleştirme işleci (??) kullanın veya isset() değerini denetleyin.

Hatalara Dayanıklı Kodlama

Bağlam kullanan bloklar, üst bloğun bulunmadığı durumu her zaman ele almalıdır. Kullanıcı bloğu amaçlanan üst bloğun dışında ekleyebilir veya üst blokta belirli bir alan için değer ayarlanmamış olabilir.

PHP
<?php
// Always provide defaults
$section = $context['my-theme/section'] ?? array();
$theme   = $section['theme'] ?? 'light';
$spacing = $section['spacing'] ?? 'md';
?>

Alt bloğun yalnızca üst bloğunun içinde görünmesini zorunlu kılmak istiyorsanız parent özelliğini ekleyin:

JSON
{
  "parent": ["my-theme/section"]
}

Kullanıcı bir my-theme/section bloğunun içinde değilken bu özellik bloğu ekleyiciden kaldırır. parent olmadan blok her yerde görünür; eksik bağlamı düzgünce ele alma sorumluluğu şablonunuza aittir.

Kapsayıcısının dışında anlam ifade etmeyen bloklarda (fiyatlandırma katmanları, kart ızgarası öğeleri) parent kullanın. Kendi başına çalışabilen ancak üst bloktan ek stil alan bloklarda (bağımsız da kullanılabilen bölüm başlıkları gibi) kullanmayın.

İpuçları

Bağlam salt okunurdur. Alt bloklar bağlam üzerinden üst bloğun özniteliklerini değiştiremez. Veri yukarı değil, aşağı doğru akar. Bir alt bloğun üst bloğa bir şey iletmesi gerekiyorsa farklı bir yöntem kullanmanız gerekir (örneğin Interactivity API üzerinden paylaşılan sunucu durumu veya gönderi üst verileri).

Tüm öznitelikler sunulur. Blockstudio yalnızca seçtiklerinizi değil, üst bloğun tüm özniteliklerini sunar. Böylece alt blok üst bloğun tanımladığı her alana erişebilir. Üst blok daha sonra yeni bir alan eklerse alt bloklar herhangi bir yapılandırma değişikliği olmadan bu alana otomatik olarak erişebilir.

Dönüştürülmüş değerler. Bağlam değerleri Blockstudio öznitelik dönüştürme işlem hattından geçer. Dosya alanları ekin tüm verilerini (url, alt, width, height) içerir, seçim alanları returnFormat kurallarına uyar ve tekrarlayıcılar özyinelemeli olarak genişletilir. Üst şablondaki $a ile aynı veri yapısını alırsınız.

Düzenleyicide reaktivite. Kullanıcı düzenleyicide bir üst blok alanını değiştirdiğinde alt bloklar otomatik olarak yeniden oluşturulur. Bu özellik, bağlam değişikliklerini algılayan ve alt bloğun sunucu tarafında yeniden oluşturulmasını tetikleyen bir React useEffect ile WordPress yerleşik bağlam aktarımını kullanır.

Bağlamı sade tutun. Blockstudio tüm üst blok özniteliklerini otomatik olarak sunsa da alt bloklar yalnızca gerçekten ihtiyaç duydukları değerleri okumalıdır. Bu bir performans konusu değildir (veriler zaten mevcuttur), kodun anlaşılır olmasıyla ilgilidir. Gelecekteki geliştiricilerin aradaki ilişkiyi bilmesi için alt bloğun hangi üst blok alanlarına bağlı olduğunu belgeleyin.

Sonraki Adımlar

  • Bağlam başvurusu: şablon değişkenleri, döngü bağlamı ve $block veri yapısı.
  • InnerBlocks: <InnerBlocks /> bileşeni, allowedBlocks, şablonlar ve ön yüz sarmalayıcı filtresi.
  • Interactivity kılavuzu: bloklar arasında istemci tarafı reaktivite için (Interactivity API, bağlamın karşılayamadığı ihtiyaçları ele alır: alt bloktan üst bloğa iletişim, bloklar arası durum ve kullanıcı tarafından tetiklenen güncellemeler).