Lewati ke konten

Merender Atribut

Di dalam file template, semua atribut dapat diakses menggunakan variabel $attributes atau $a serta ID field yang bersangkutan.

PHP

PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>

Twig

Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>

Menulis Atribut Secara Terprogram

Editor menyimpan nilai di bawah blockstudio.attributes. Apa pun yang menulis blok di luar editor, seperti REST API, WP-CLI, migrasi konten, atau server MCP, menemukan blok melalui atribut yang didaftarkan Blockstudio pada WP_Block_Type, lalu menulisnya di level teratas. Kedua struktur ini dapat dirender:

PHP
// Top level, as a programmatic writer produces it.
echo do_blocks( '<!-- wp:acme/hero {"visual_type":"media"} /-->' );

// Nested, as the editor saves it.
echo do_blocks( '<!-- wp:acme/hero {"blockstudio":{"attributes":{"visual_type":"media"}}} /-->' );

Hanya ID yang dideklarasikan blok yang dibaca dari level teratas, jadi atribut milik WordPress sendiri seperti anchor, className, lock, metadata, dan style tidak pernah digunakan sebagai nilai field. Jika ID yang sama muncul di kedua tempat, nilai bertingkat yang diutamakan.

Membaca Atribut Secara Terprogram

Kode yang berjalan di luar template, seperti data terstruktur di save_post, ekspor, pengindeksan pencarian, atau filter render_block, sering kali memerlukan nilai blok tersimpan sebagaimana terlihat oleh template. bs_block_values() mengembalikannya tanpa merender blok. Panggil setelah pendaftaran blok (init atau setelahnya) dengan array attrs lengkap dari parse_blocks():

PHP
foreach (parse_blocks($post->post_content) as $block) {
  if ($block['blockName'] === null) {
    continue;
  }

  $a = bs_block_values($block['blockName'], $block['attrs']);

  if ($a === null) {
    // Not a Blockstudio block, and no extension applies.
    continue;
  }

  echo esc_html($a['title'] ?? '');
}

Hasilnya adalah array $a milik template, dengan kunci berupa ID field:

  • Default field berlaku, dan repeater dengan min memiliki baris awalnya.
  • Nilai tingkat teratas dan blockstudio.attributes digabungkan, dan nilai yang bersarang akan digunakan. Hanya id yang dideklarasikan yang dibaca dari tingkat teratas, dan WordPress menghapus nilai tingkat teratas yang tidak cocok dengan tipe terdaftar field, misalnya string select, persis seperti saat dirender.
  • Field dari ekstensi yang cocok disertakan, beserta default-nya. Ekstensi dari blok inti atau pihak ketiga hanya membaca blockstudio.attributes, seperti saat dirender.
  • Format pengembalian diterapkan, sehingga select dengan returnFormat dari label memberikan label dan field files memberikan data lampiran.
  • Field yang dinonaktifkan dan kosong false, seperti di template.

null berarti blok maupun ekstensi tidak dikelola oleh Blockstudio. Blok Blockstudio tanpa field menghasilkan [].

Fungsi ini menjalankan transformasi yang sama seperti proses rendering, sehingga efek sampingnya pun sama: field file mengkueri lampiran, field blok yang tidak mengembalikan data merender blok yang dirujuk, dan filter blockstudio/blocks/attributes/render dijalankan untuk setiap nilai. Fungsi ini tidak merender template blok itu sendiri dan tidak menyelesaikan innerBlocks; telusuri sendiri. Field kode mempertahankan ID %selector% yang dihasilkan dan berbeda di setiap pemanggilan.

Resolusi menggunakan konteks WordPress saat ini. Metadata khusus rendering seperti penghitung blok dan innerBlocks tidak dibuat; filter render atribut menerima nama blok, bukan metadata blok yang sudah dirender sepenuhnya.

Tidak ada opsi untuk nilai yang tersimpan tanpa transformasi. Baca array attrs secara langsung untuk mendapatkannya, atau gunakan bs_validate_block() untuk memeriksanya.

Nilai Kosong

Nilai atribut mengembalikan false jika field kosong atau tidak ada opsi yang dipilih.

PHP

PHP
<?php if ($a['message']) : ?>
  <h1><?php echo $a['message']; ?></h1>
<?php endif; ?>

Twig

Twig
{% if a.message %}
  <h1>{{ a.message }}</h1>
{% endif %}

Tipe Kompleks

File

Secara default (tanpa returnFormat, atau dengan "returnFormat": "object"), field file mengembalikan array berisi data lampiran. Dengan "multiple": true, field ini mengembalikan daftar array tersebut. File yang lampirannya sudah tidak ada akan false.

Kunci Deskripsi
ID ID lampiran.
title Judul lampiran.
alt Teks alternatif. Jika kosong, menggunakan judul lampiran.
caption Keterangan.
description Deskripsi.
href Permalink halaman lampiran.
url URL file. Dengan menu tarik-turun ukuran ("size": true), URL untuk ukuran yang dipilih.
sizes URL dan dimensi setiap ukuran gambar yang terdaftar; lihat di bawah.

PHP

PHP
<?php if ($a['image']) :
  $image = $a['image'];
  $sizes = $image['sizes'] ?? [];
?>
  <img
    src="<?php echo esc_url($sizes['large'] ?? $image['url']); ?>"
    alt="<?php echo esc_attr($image['alt']); ?>"
    <?php if (isset($sizes['large-width'], $sizes['large-height'])) : ?>
      width="<?php echo esc_attr($sizes['large-width']); ?>"
      height="<?php echo esc_attr($sizes['large-height']); ?>"
    <?php endif; ?>
  />
<?php endif; ?>

Twig

Twig
{% if a.image %}
  <img
    src="{{ (a.image.sizes.large ?? a.image.url)|e('html_attr') }}"
    alt="{{ a.image.alt|e('html_attr') }}"
    {% if a.image.sizes['large-width'] is defined and a.image.sizes['large-height'] is defined %}
      width="{{ a.image.sizes['large-width']|e('html_attr') }}"
      height="{{ a.image.sizes['large-height']|e('html_attr') }}"
    {% endif %}
  />
{% endif %}

sizes memiliki satu entri untuk setiap ukuran gambar terdaftar ditambah full: URL di bawah nama ukuran, serta dimensinya di bawah <size>-width dan <size>-height. Ukuran WordPress yang belum dibuat untuk lampiran akan merujuk ke file asli beserta dimensinya. Jika WordPress tidak dapat menemukan gambar atau pratinjau, kunci sizes tidak ada. Misalnya, PDF tanpa pratinjau yang dibuat tidak memiliki sizes, tetapi PDF dengan metadata pratinjau dapat memiliki ukuran gambar. sizes adalah null jika tidak ada ukuran gambar yang terdaftar atau jika filter files/sizesfilter menonaktifkannya. Filter tersebut juga dapat mempersingkat peta, jadi pastikan ukuran tersedia sebelum membaca dimensinya, seperti pada contoh di atas.

Objek ini tidak memiliki kunci width, height, mime, type, atau size. Baca dimensinya dari sizes, atau gunakan ID dengan fungsi seperti wp_get_attachment_image() dan get_post_mime_type().

Format pengembalian

returnFormat mengubah nilai yang dikembalikan field:

returnFormat Nilai
"object" (default) Array yang dijelaskan di atas.
"id" ID lampiran seperti yang disimpan, atau daftar ID dengan "multiple": true.
"url" URL sebagai string, atau daftar URL dengan "multiple": true. Gambar menggunakan set ukuran dari returnSize (default full), sedangkan file lain menggunakan file URL.

Field tautan mengembalikan objek dengan URL dan atribut:

PHP

PHP
<?php if ($a['link']) : ?>
  <a
    href="<?php echo $a['link']['url']; ?>"
    target="<?php echo $a['link']['target']; ?>"
  >
    <?php echo $a['link']['title']; ?>
  </a>
<?php endif; ?>

Twig

Twig
{% if a.link %}
  <a href="{{ a.link.url }}" target="{{ a.link.target }}">
    {{ a.link.title }}
  </a>
{% endif %}

Ikon

Field ikon mengembalikan objek dengan key set, subSet, dan icon. Gunakan fungsi helper bs_render_icon() dan bs_icon() untuk menghasilkan SVG:

PHP

PHP
<?php if ($a['icon']) : ?>
  <div class="icon">
    <?php bs_render_icon($a['icon']); ?>
  </div>
<?php endif; ?>

Twig

Twig
{% if a.icon %}
  <div class="icon">
    {{ bs_icon(a.icon) }}
  </div>
{% endif %}

bs_render_icon() langsung mencetak SVG. bs_icon() mengembalikannya sebagai string.

Atribut

Tipe field attributes mengembalikan array pasangan {attribute, value} untuk dirender sebagai atribut HTML. Gunakan bs_render_data_attributes() untuk menampilkannya:

PHP

PHP
<div <?php bs_render_data_attributes($a['attributes']); ?>>
  Content
</div>

Twig

Twig
<div {{ fn('bs_render_data_attributes', a.attributes) }}>
  Content
</div>

bs_render_data_attributes() langsung mencetak atribut. bs_data_attributes() mengembalikan string.

Grup

Field grup menambahkan nama grup sebagai awalan pada ID atribut turunannya. Gunakan bs_get_group() untuk mengekstrak field grup menjadi array yang bersih:

PHP

PHP
<?php $group = bs_get_group($a, 'settings'); ?>
<h1><?php echo $group['title']; ?></h1>
<p><?php echo $group['description']; ?></p>

Twig

Twig
{% set group = fn('bs_get_group', a, 'settings') %}
<h1>{{ group.title }}</h1>
<p>{{ group.description }}</p>

Ini menghapus awalan grup dari key atribut. Misalnya, $a['settings_title'] menjadi $group['title'].

Helper ini juga berfungsi saat grup berasal dari field kustom yang digunakan ulang:

JSON
{
  "name": "section-header",
  "attributes": [
    {
      "id": "section-header",
      "type": "group",
      "attributes": [
        { "id": "kicker", "type": "text" },
        { "id": "title", "type": "text" }
      ]
    }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [
      { "type": "custom/section-header" }
    ]
  }
}
Twig
{% set sectionHeader = fn('bs_get_group', a, 'section-header') %}
<p>{{ sectionHeader.kicker }}</p>
<h2>{{ sectionHeader.title }}</h2>

Repeater

Telusuri item repeater dalam loop:

PHP

PHP
<?php foreach ($a['items'] as $item) : ?>
  <div class="item">
    <h3><?php echo $item['title']; ?></h3>
    <p><?php echo $item['description']; ?></p>
  </div>
<?php endforeach; ?>

Twig

Twig
{% for item in a.items %}
  <div class="item">
    <h3>{{ item.title }}</h3>
    <p>{{ item.description }}</p>
  </div>
{% endfor %}

Buku Resep Pola Field