Lewati ke konten

Konteks Block dan Komunikasi

Sebagian besar block berdiri sendiri. Block memiliki field dan template masing-masing, serta tidak terpengaruh oleh elemen di sekitarnya. Namun, beberapa komponen secara alami memiliki hierarki: kisi kartu dengan jumlah kolom dan jarak yang diatur oleh induknya, tabel harga dengan mata uang yang ditentukan oleh induknya, atau pembungkus bagian yang memberi tahu anak-anaknya untuk menggunakan tema terang atau gelap.

WordPress menyediakan konteks block API untuk kebutuhan ini. Block induk membuka akses ke sebagian datanya, dan block anak berlangganan ke data tersebut. Saat induk berubah, anak-anaknya otomatis diperbarui. Blockstudio menyederhanakan proses ini secara signifikan: Anda tidak perlu mengonfigurasi providesContext sama sekali. Setiap block Blockstudio otomatis menyediakan semua atributnya sebagai konteks. Block anak hanya perlu satu baris di block.json untuk berlangganan.

Panduan ini membuat empat pola komponen dunia nyata yang menggunakan konteks, masing-masing menunjukkan kebutuhan komunikasi yang berbeda.

Cara Kerja Konteks di Blockstudio

Di WordPress standar, Anda harus secara eksplisit memetakan setiap atribut induk ke kunci konteks di providesContext, lalu mencantumkan kunci tersebut di usesContext anak. Blockstudio menghilangkan seluruh langkah pertama.

Block induk: Tidak perlu konfigurasi. Setiap block Blockstudio otomatis menyediakan semua atributnya dengan nama block sebagai kuncinya.

Block anak: Tambahkan usesContext dengan nama block induk:

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

Template anak: Akses atribut induk melalui $context (atau bentuk singkat $c):

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

Hanya itu pengaturannya. Tidak perlu providesContext di induk, pemetaan atribut, atau kode registrasi. Anak menerima semua atribut induk yang telah ditransformasi. Artinya, field media diuraikan menjadi data lampiran, field select mengikuti returnFormat, dan repeater diperluas sepenuhnya.

Dua jenis konteks

Blockstudio menyediakan dua variabel konteks dalam template, dan keduanya memiliki tujuan berbeda:

Variabel Berisi Kasus penggunaan
$context / $c Atribut block induk (melalui usesContext) Komunikasi komponen
$block['context'] / $b['context'] Data loop WordPress (postId, postType) Loop block kueri

Jenis pertama digunakan agar block dapat berkomunikasi dengan induknya. Jenis kedua digunakan oleh block di dalam loop Query yang perlu mengetahui pos yang sedang dirender. Panduan ini berfokus pada jenis pertama.

Dukungan editor

Pembaruan konteks bersifat reaktif di editor. Saat pengguna mengubah nilai field block induk, semua block anak yang berlangganan konteks induk tersebut otomatis dirender ulang dengan nilai baru. Tidak perlu menyegarkan secara manual.

Pembungkus Bagian

Pola konteks yang paling umum: block pembungkus yang menyediakan pengaturan tema untuk anak-anaknya. Induk memiliki field untuk warna latar, warna teks, dan padding. Anak-anak membaca nilai ini agar gayanya konsisten.

Induk: Bagian

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>

Anak: Judul Bagian

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>

Yang ditunjukkan: Judul tidak memiliki field warna sendiri. Judul membaca nilai theme bagian dari konteks dan menyesuaikan diri. Saat pengguna mengubah bagian dari “Terang” ke “Gelap” di editor, warna teks judul langsung diperbarui.

Properti parent di block.json anak membatasi tempat block dapat disisipkan. Block hanya muncul di inserter saat pengguna berada di dalam block my-theme/section. Pengaturan ini opsional, tetapi disarankan untuk block yang hanya masuk akal jika berada di dalam induk tertentu.

Anak: Teks Bagian

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>

Kini judul dan teks sama-sama mengikuti tema bagian. Pengguna memilih tema sekali pada induk, lalu setiap anak menyesuaikan diri.

Kisi Kartu

Block induk berbentuk kisi yang mengatur setelan tata letak untuk kartu anaknya. Induk menentukan kolom dan jarak. Anak menggunakan nilai ini untuk memahami konteks tata letaknya dan menyesuaikan gaya.

Induk: Kisi Kartu

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>

Anak: Kartu

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>

Yang ditunjukkan: Kartu tidak memiliki field gaya sendiri. Kartu membaca cardStyle dari induk kisi. Saat pengguna mengubah kisi dari “Terangkat” ke “Berbingkai”, semua kartu di kisi langsung diperbarui. Ini menjaga konsistensi tampilan kartu tanpa mengharuskan pengguna memperbaruinya satu per satu.

Atribut template pada <InnerBlocks> mengisi kisi dengan tiga kartu sebagai titik awal bagi pengguna.

Tabel Harga

Pola yang lebih canggih dengan induk yang menyediakan logika bisnis bersama (mata uang, periode penagihan) untuk digunakan anak-anaknya saat menampilkan data. Ini menghindari duplikasi field yang sama di setiap tingkat harga.

Induk: Tabel Harga

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>

Anak: Tingkat Harga

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>

Yang ditunjukkan: Simbol mata uang dan periode penagihan ditentukan sekali di tabel harga dan diwariskan oleh setiap tingkat. Saat pengguna mengubah mata uang dari USD ke EUR, simbol mata uang di ketiga tingkat diperbarui secara bersamaan. Tanpa konteks, Anda harus menduplikasi field mata uang di setiap tingkat dan menyelaraskannya secara manual.

Konteks Loop Kueri

Ada jenis konteks terpisah yang disediakan WordPress di dalam loop block Query. Saat block dirender di dalam loop, $block['context'] (atau $b['context']) berisi data pos untuk iterasi saat ini:

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>

Ini berbeda dari konteks block induk ($context / $c). Konteks loop disediakan oleh inti WordPress dan hanya berisi postId serta postType. Anda tidak perlu usesContext di block.json untuk ini. Blockstudio otomatis membuat setiap block berlangganan ke postId dan postType.

Kegunaan konteks loop: Kartu pos kustom di dalam block Query, block yang menampilkan meta pos, atau block apa pun yang perlu dirender secara berbeda untuk setiap pos dalam loop.

Anda juga dapat mengakses data pos halaman luar, apa pun konteks loopnya:

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

Konteks Bersarang

Konteks mengalir melalui seluruh pohon block, bukan hanya satu tingkat. Jika block A berisi block B, yang berisi block C, C dapat berlangganan ke konteks A. Ini berfungsi karena WordPress meneruskan konteks ke setiap tingkat InnerBlocks.

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

Judul tidak harus menjadi anak langsung bagian. Judul dapat berada di dalam block inti (kolom, grup, dan sebagainya) dan tetap menerima konteks bagian. Langganan usesContext berfungsi pada kedalaman berapa pun.

Beberapa induk

Sebuah anak dapat berlangganan ke beberapa induk:

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';
?>

Jika induk tidak ditemukan di pohon leluhur, kuncinya tidak akan ada di $context. Selalu gunakan operator penggabungan null (??) atau periksa isset() saat membaca nilai konteks, untuk berjaga-jaga jika block digunakan di luar induk yang diharapkan.

Penulisan Kode Defensif

Block yang menggunakan konteks harus selalu menangani kondisi saat induknya tidak ada. Pengguna mungkin menyisipkan block di luar induk yang dituju, atau block induk mungkin tidak memiliki nilai untuk field tertentu.

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

Untuk memastikan anak hanya muncul di dalam induknya, tambahkan properti parent:

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

Ini menghapus block dari inserter saat pengguna tidak berada di dalam block my-theme/section. Tanpa parent, block akan muncul di mana saja, dan template Anda bertanggung jawab menangani konteks yang tidak tersedia dengan baik.

Gunakan parent untuk block yang tidak bermakna di luar kontainernya (tingkat harga, item kisi kartu). Jangan gunakan untuk block yang tetap berfungsi sendiri tetapi mendapat gaya tambahan dari induk (judul bagian yang juga dapat digunakan secara mandiri).

Tips

Konteks hanya dapat dibaca. Anak tidak dapat mengubah atribut induk melalui konteks. Data mengalir ke bawah, tidak pernah ke atas. Jika anak perlu mengirimkan sesuatu kepada induknya, Anda memerlukan pendekatan lain (seperti state server bersama melalui API Interactivity, atau meta pos).

Semua atribut disediakan. Blockstudio menyediakan setiap atribut block induk, bukan hanya yang Anda pilih. Artinya, anak dapat mengakses field apa pun yang ditentukan induk. Jika induk kemudian menambahkan field baru, anak otomatis dapat mengaksesnya tanpa perubahan konfigurasi.

Nilai yang ditransformasi. Nilai konteks melewati pipeline transformasi atribut milik Blockstudio. Field file berisi data lampiran lengkap (url, alt, width, height), field select mengikuti returnFormat, dan repeater diperluas secara rekursif. Anda mendapatkan struktur data yang sama seperti $a di template induk.

Reaktivitas editor. Saat pengguna mengubah field induk di editor, block anak otomatis dirender ulang. Fitur ini menggunakan propagasi konteks bawaan WordPress dengan React useEffect yang mendeteksi perubahan konteks dan memicu render ulang anak di sisi server.

Jaga konteks tetap ringkas. Meskipun Blockstudio otomatis menyediakan semua atribut induk, anak sebaiknya hanya membaca nilai yang benar-benar diperlukan. Ini bukan soal kinerja (datanya sudah tersedia), melainkan kejelasan kode. Dokumentasikan field induk yang menjadi dependensi anak agar pengembang berikutnya memahami hubungannya.

Langkah Berikutnya

  • Referensi konteks: variabel template, konteks loop, dan struktur data $block.
  • InnerBlocks: komponen <InnerBlocks />, allowedBlocks, template, dan filter pembungkus frontend.
  • Panduan Interactivity: untuk reaktivitas sisi klien antarblock (API Interactivity menangani hal-hal yang tidak dapat dilakukan konteks: komunikasi dari anak ke induk, state antarblock, dan pembaruan yang dipicu pengguna).