Merender Atribut
Di dalam file template, semua atribut dapat diakses menggunakan variabel $attributes atau $a serta ID field yang bersangkutan.
PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>
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:
// 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():
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
minmemiliki baris awalnya. - Nilai tingkat teratas dan
blockstudio.attributesdigabungkan, 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
returnFormatdarilabelmemberikan 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 if ($a['message']) : ?>
<h1><?php echo $a['message']; ?></h1>
<?php endif; ?>
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 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
{% 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. |
Tautan
Field tautan mengembalikan objek dengan URL dan atribut:
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
{% 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 if ($a['icon']) : ?>
<div class="icon">
<?php bs_render_icon($a['icon']); ?>
</div>
<?php endif; ?>
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
<div <?php bs_render_data_attributes($a['attributes']); ?>>
Content
</div>
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 $group = bs_get_group($a, 'settings'); ?>
<h1><?php echo $group['title']; ?></h1>
<p><?php echo $group['description']; ?></p>
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:
{
"name": "section-header",
"attributes": [
{
"id": "section-header",
"type": "group",
"attributes": [
{ "id": "kicker", "type": "text" },
{ "id": "title", "type": "text" }
]
}
]
}
{
"blockstudio": {
"attributes": [
{ "type": "custom/section-header" }
]
}
}
{% 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 foreach ($a['items'] as $item) : ?>
<div class="item">
<h3><?php echo $item['title']; ?></h3>
<p><?php echo $item['description']; ?></p>
</div>
<?php endforeach; ?>
Twig
{% for item in a.items %}
<div class="item">
<h3>{{ item.title }}</h3>
<p>{{ item.description }}</p>
</div>
{% endfor %}