Lewati ke konten

Perenderan Programatis

Karena Gutenberg semakin menjadi perangkat utama untuk membuat situs yang mudah diedit bagi klien, masuk akal untuk membuat semua area situs yang diperlukan sebagai blok. Pendekatan ini cocok untuk sebagian besar kebutuhan, tetapi pengguna tingkat lanjut dan kasus penggunaan tertentu mungkin perlu menggunakan blok yang sudah ada di luar editor.

Blockstudio menyediakan dua pendekatan untuk merender blok secara programatis:

  • Fungsi PHP: bs_render_block dan bs_block untuk merender dari kode PHP
  • Tag HTML: tag <bs:block-name> yang diganti dengan output blok di mana saja pada halaman

Semua fitur khusus Blockstudio seperti gaya inline, skrip, dan gaya dengan cakupan terbatas didukung.

Islands juga berfungsi melalui jalur render ini. Island dinamis yang dirender dengan bs_render_block(), bs_block(), atau tag blok mengembalikan penanda placeholder yang sama seperti blok yang dirender dari konten pos, dan runtime frontend disisipkan saat penanda tersebut ada dalam respons.

Komposisi Terstruktur dan Dokumen Lengkap

Untuk alat, pratinjau, ekspor, dan galeri komponen yang digunakan dalam jangka panjang, gunakan Blockstudio\Render API berversi. Fitur ini menerima satu deklarasi atau daftar berurutan, lalu merender tanpa melakukan echo:

PHP
use Blockstudio\Render;

$composition = [
  'root' => 'theme/card',
  'example' => [
    'data' => [
      'heading' => 'Example card',
    ],
    'layers' => [
      [
        'name' => 'theme/button',
        'data' => [
          'label' => 'Continue',
        ],
      ],
    ],
  ],
];

$normalized = Render::normalize($composition);
$html = Render::composition($composition);
$document = Render::document($composition, [
  'title' => 'Component preview',
  'contentElement' => 'main',
  'contentClasses' => ['component-preview'],
]);

Deklarasi ternormalisasi kanonis memiliki empat kunci:

PHP
[
  'name' => 'theme/card',
  'attributes' => [],
  'content' => '',
  'children' => [],
]

data, inner, innerBlocks, root, layers, dan example adalah kemudahan input yang akan dinormalisasi dan dihapus. Deklarasi bertingkat dirender secara rekursif melalui pipeline Blockstudio yang sama.

Render::document() mengembalikan schemaVersion, html, body, blocks, assets, warnings, dan errors. Nilai assets memisahkan head, footer, styles, scripts, modules, interactivity, ui, dan tailwind. Daftar blok dan aset mencakup dependensi yang dirujuk oleh templat terpilih, tetapi mengecualikan aset yang tidak terkait dan khusus editor.

Dokumen lengkap dapat menetapkan bodyClasses/bodyAttributes dan secara opsional membungkus isi yang dirender dengan contentElement, contentClasses, dan contentAttributes. Pembungkus dibatasi pada nama elemen yang aman; nilai body yang dikembalikan tetap berupa konten hasil render tanpa pembungkus. Opsi head dan footer menambahkan markup dokumen tepercaya pada posisi masing-masing dan disertakan dalam kumpulan aset yang dikembalikan.

Untuk menyusun dokumen di sekitar HTML yang sudah dirender, berikan nama blok root yang diketahui:

PHP
$document = Render::document_from_html(
  $rendered_html,
  ['theme/hero', 'theme/button'],
  ['title' => 'Homepage preview']
);

Gunakan Render::content() untuk konten blok WordPress yang diserialisasi. Konsumen yang merender beberapa dokumen independen dalam satu permintaan harus memanggil Blockstudio\Batch_Render::reset() di antaranya; Canvas::documents() melakukannya secara otomatis.

Merender di Luar Halaman

Blockstudio menambahkan komentar <!--blockstudio/namespace/slug--> sebelum tiap blok yang direndernya. Pada halaman frontend, buffer membaca komentar ini untuk mengetahui blok yang ada, memuat asetnya, lalu menghapus komentar sebelum respons dikirim.

Output yang tidak melewati buffer tersebut akan tetap menyertakan komentar. Ini berlaku untuk respons REST, feed, penangan AJAX, dan HTML yang Anda simpan atau kirim ke tempat lain setelah do_blocks(), Render::content(), atau bs_render_block(). Gunakan bs_strip_render_markers() untuk menghapusnya:

PHP
$html = bs_strip_render_markers(do_blocks($post->post_content));

Fungsi ini menghapus komentar blok Blockstudio yang terdaftar dan membiarkan semua yang lain tetap utuh, termasuk komentar HTML lainnya. Fungsi ini mencocokkan penanda yang sama dengan yang dihapus buffer halaman. Panggil setelah pendaftaran blok (init atau sesudahnya).

Jangan hapus markup yang masih dicetak ke halaman frontend yang melewati buffer. Halaman memerlukan komentar tersebut untuk mengetahui aset blok yang perlu dimuat, dan Blockstudio akan menghapusnya sendiri di akhir.

Menghapus komentar tidak menambahkan aset. Berkas blok CSS dan JavaScript hanya disuntikkan oleh buffer halaman. Gunakan bs_block_assets() atau Render::document() jika konsumen juga memerlukannya.

Memeriksa Blok

Gunakan bs_block_fields() setelah pendaftaran blok (pada init atau sesudahnya) untuk mendapatkan definisi bidang yang telah diselesaikan tanpa membaca registri internal:

PHP
$fields = bs_block_fields('theme/card');

if ($fields === null) {
  // Unknown block, or not a Blockstudio block.
}

Nilai yang dikembalikan adalah larik definisi bidang terdaftar, termasuk filter atribut, bidang kustom yang diperluas, penggantian, serta grup, tab, dan repeater bertingkat. Blok Blockstudio tanpa bidang mengembalikan []. Hasilnya adalah salinan: perubahan padanya tidak mengubah blok yang terdaftar.

Ini adalah definisi, bukan nilai tersimpan. Untuk memvalidasi markup tersimpan, gunakan validator markupbs_validate_block() alih-alih mengelola penelusur field terpisah. Untuk menjelaskan nilai yang diterima sebuah blok, gunakan schema nilaibs_block_schema(). Atribut milik WordPress tetap terpisah.

Bidang yang ditambahkan oleh ekstensi bukan bagian dari bs_block_fields(). Gunakan bs_block_extension_fields() untuk mendapatkannya. Fungsi ini mencocokkan ekstensi berdasarkan nama blok, sehingga juga berfungsi untuk blok inti dan pihak ketiga:

PHP
$fields = array_merge(
  bs_block_fields('core/paragraph') ?? [],
  bs_block_extension_fields('core/paragraph')
);

Nilai yang dikembalikan mencantumkan definisi bidang dari setiap ekstensi yang cocok, sesuai urutan pendaftaran ekstensi, dengan struktur yang sama seperti bs_block_fields(). Blok yang tidak cocok dengan ekstensi mana pun mengembalikan []. Nilai ekstensi tersimpan dalam objek attrs.blockstudio.attributes yang sama dengan nilai bidang milik blok itu sendiri, sehingga semua ID berbagi satu namespace. Jika dua ekstensi mendefinisikan ID yang sama, kedua definisi dikembalikan dan mengedit nilai yang sama; saat dirender, definisi dari ekstensi yang didaftarkan belakangan akan berlaku.

Untuk membaca nilai blok tersimpan seperti yang diterima templatnya, gunakan bs_block_values().

Gunakan bs_block_assets() untuk memeriksa CSS dan JavaScript yang ditemukan pada blok. Untuk dokumen pratinjau lengkap, termasuk blok bertingkat dan dependensi runtime bersama, gunakan Render::document() seperti dijelaskan di atas.

Memvalidasi nilai tersimpan

Gunakan bs_validate_block() setelah pendaftaran blok (init atau sesudahnya) untuk memeriksa atribut blok yang dibuat secara terprogram atau diimpor sebelum menyimpannya:

PHP
$block = parse_blocks($content)[0];
$findings = bs_validate_block($block['blockName'], $block['attrs']);

if ($findings === null) {
  // No Blockstudio fields or matching extensions apply.
} elseif ($findings === []) {
  // No stored-value problems were found.
} else {
  // Review the findings before saving.
}

Teruskan larik attrs lengkap, bukan hanya blockstudio.attributes. Render Blockstudio juga menerima bidang yang dideklarasikan di tingkat teratas, dan nilai bertingkat akan diutamakan jika keduanya diberikan. Ekstensi blok inti dan pihak ketiga hanya membaca blockstudio.attributes. Blok Blockstudio kosong tetap dikelola dan mengembalikan [], bukan null.

Validasi ini bersifat eksplisit dan hanya membaca. Proses ini tidak merender templat, mengubah nilai, menyimpan pos, mengkueri media, atau menjalankan callback populate. Proses ini tidak berjalan otomatis saat penyimpanan, sinkronisasi halaman, atau rendering. Proses ini bukan sanitizer, pemeriksaan otorisasi, atau pemeriksaan keberadaan lampiran.

Setiap temuan berisi kunci stabil berikut:

PHP
[
  'code' => 'unknown_option',
  'path' => 'steps/1/style',
  'source' => 'block',
  'message' => 'This value is not among the field options.',
  'value' => 'c',
  'expected' => ['a', 'b'],
]

Gunakan code, bukan message yang diterjemahkan, dalam perkakas. source adalah block atau extension. Path menggunakan kunci penyimpanan dan indeks baris repeater atau pilihan berbasis nol, tanpa garis miring di awal. ~ dan / literal dalam kunci di-escape sebagai ~0 dan ~1. Grup tingkat atas menjadi awalan bagi turunannya (cta_title); grup dan tab anonim tidak menambahkan tingkat. Builder tidak mendukung grup dengan ID di dalam grup lain atau repeater, sehingga kuncinya tidak diterima. Kolom pesan tidak memiliki nilai tersimpan. Kolom files mengizinkan pasangannya, <id>__size. Di root blok Blockstudio, kunci pencatatan dan atribut global HTML yang diteruskan ke elemen hasil render bukanlah kolom yang tidak dikenal. Ini tidak mengizinkan kunci sembarang dalam baris repeater atau ekstensi blok inti.

Kode Arti expected
unknown_field Tidak ada kolom yang dipertahankan yang mendeklarasikan kunci penyimpanan ini. Kunci penyimpanan yang dikenal.
unknown_option Pilihan tidak termasuk dalam opsi yang dikenal. Nilai opsi yang diizinkan.
wrong_type Bentuk tersimpan tidak didukung oleh kolom. Keluarga atau tipe penyimpanan yang diharapkan.
too_few_rows, too_many_rows Repeater yang tersedia berada di luar min atau max. Batas baris.
definition_conflict Definisi yang berlaku untuk satu kunci memerlukan bentuk penyimpanan yang berbeda. Sumber dan tipe kolom dari setiap definisi.
shadowed_value Nilai bertingkat menimpa nilai kolom tingkat atas yang berbeda. Nilai bertingkat yang menang.
extension_top_level Templat dapat membaca nilai tingkat atas, tetapi binding ekstensi tidak. Path yang diwajibkan di bawah blockstudio/attributes.
unknown_attribute Kunci tingkat atas dari blok Blockstudio tidak dibaca oleh path render dan dihapus. Nama atribut terdaftar, kolom ekstensi, dan blockstudio.
missing_container attributes, disabled, name atau editor disimpan di tingkat atas dan blockstudio tidak tersedia. Path yang diwajibkan di bawah blockstudio.
invalid_container blockstudio atau blockstudio.attributes bukan objek. object.

Pesan temuan unknown_field menyebutkan kunci penyimpanan terdekat pada tingkat yang sama jika jaraknya paling banyak tiga edit, sebagaimana aturan untuk setelan yang tidak dikenal: This storage key is not declared by the block or its extensions. Did you mean "title"? expected tetap mencantumkan setiap kunci yang dikenal. Pencocokan mengabaikan kapitalisasi dan hanya mempertimbangkan kunci penyimpanan dari kontainer tersebut. Pesan diterjemahkan; integrasi sebaiknya menggunakan code, path, dan expected alih-alih mengurai teks pesan.

Kunci tingkat atas dari blok Blockstudio yang bukan atribut terdaftar (kolomnya, atribut yang ditambahkan WordPress untuk supports, lock dan metadata), kolom dari ekstensi yang cocok, maupun blockstudio, kunci pencatatan, atau atribut HTML yang diteruskan akan dihapus sebelum templat dijalankan. Kunci semacam itu, misalnya ID kolom yang salah ketik atau objek nilai yang disimpan tanpa pembungkus blockstudio, menghasilkan temuan karena blok dirender tanpa nilai tersebut. Blok yang hanya memuat kolom ekstensi tidak diperiksa untuk kunci tingkat atas.

Bentuk yang diterima mengikuti proses render: pilihan ganda dan kotak centang dapat berisi daftar, satu objek opsi, atau skalar yang diimpor, termasuk nol numerik. String numerik diterima untuk angka. Kolom berkas dapat berisi ID lampiran, objek ID, daftar, atau referensi string. Nilai tautan dan ikon harus berupa objek; tipe kolom kustom menggunakan tipe atribut yang terdaftar. Kolom attributes menyimpan daftar pasangan dengan nama attribute yang tidak kosong dan nilai skalar value; metadata opsional seperti data.media tetap dipertahankan.

WordPress memvalidasi atribut tingkat atas yang terdaftar sebelum render, sehingga dapat menolak bentuk yang diterima di dalam blockstudio.attributes. Misalnya, nilai radio "a" berfungsi dalam objek bertingkat, tetapi dihapus di tingkat atas karena tipe terdaftarnya adalah object. Nilai semacam itu menghasilkan wrong_type. Gunakan objek bertingkat untuk bentuk penyimpanan yang sama dengan yang ditulis editor.

Kolom yang tidak ada tidak diwajibkan. Nilai bertingkat yang kosong (null, false, '', []) dan kolom yang dinonaktifkan tidak menghasilkan kesalahan nilai. Repeater yang secara eksplisit kosong tetap diperiksa terhadap min; repeater yang tidak ada atau dinonaktifkan tidak diperiksa. Nilai tingkat atas yang kosong dilaporkan jika WordPress menghapusnya lalu memulihkan nilai bawaan yang tidak kosong. Nilai yang sama dalam objek bertingkat dapat mengosongkannya. Konflik definisi dilaporkan meskipun kunci tersebut tidak memiliki nilai tersimpan.

Opsi statis dan opsi populate yang sudah diselesaikan saat pendaftaran diperiksa tanpa memanggil populate lagi. Opsi fetch jarak jauh dan argumen populate yang berisi {attributes.*} dilewati. Nilai warna dan gradien dapat dikustomisasi, kecuali jika disableCustomColors atau disableCustomGradients ditetapkan. Pemeriksaan ini mencakup nilai tersimpan, bukan default, fallback, atau aturan validasi editor.

Kolom ekstensi yang cocok disertakan untuk setiap blok yang ditujunya. Definisi yang lebih baru akan menang di dalam blok atau ekstensinya pada root, seperti saat render. Kolom milik blok sendiri dan kolom ekstensi tetap menjadi definisi terpisah untuk kunci yang sama dan keduanya berlaku. Di dalam baris repeater, perender membaca kolom pertama dengan ID yang cocok dari setiap sumber, sehingga opsi dan batasannya berlaku. Definisi duplikat dipertahankan untuk diagnostik konflik: bentuk penyimpanan yang tidak kompatibel menghasilkan definition_conflict, meskipun duplikat yang lebih baru tidak dibaca saat render.

Fungsi ini memeriksa satu blok. Telusuri innerBlocks saat memvalidasi dokumen; pola tersinkron dan referensi lainnya tidak diperluas secara otomatis. Perintah wp bs blocks validate menelusuri blok dari satu atau beberapa pos dan melaporkan path bloknya.

Situs dengan resolver kustom saat render dapat menyesuaikan temuan tanpa mengubah data tersimpan:

PHP
add_filter('blockstudio/blocks/attributes/validate', function($findings, $name, $attrs) {
  if ($name !== 'my-theme/card') {
    return $findings;
  }

  return array_values(array_filter($findings, function($finding) {
    return !($finding['path'] === 'customReference' && $finding['code'] === 'wrong_type');
  }));
}, 10, 3);

Selalu kembalikan daftar temuan; mengembalikan [] berarti menerima blok. Filter ini hanya berjalan untuk blok terkelola, tidak pernah untuk hasil null.

Menjelaskan nilai tersimpan

Gunakan bs_block_schema() setelah pendaftaran blok (init atau yang lebih baru) untuk menjelaskan nilai yang disimpan blok, misalnya untuk membuat markup blok di alat atau integrasi AI, atau untuk memeriksa input pada rute REST:

PHP
$schema = bs_block_schema('theme/card');

if ($schema === null) {
  // No Blockstudio fields or matching extensions apply.
}

Hasilnya adalah Schema JSON dari objek yang disimpan di attrs.blockstudio.attributes. Schema ini mencakup field blok dan field dari ekstensi yang cocok, beserta kunci penyimpanan yang digunakan validasi: grup tingkat atas memberi awalan pada turunannya, grup anonim dan tab tidak menambah tingkat, dan field file menambahkan pendamping <id>__size. Repeater berupa daftar objek baris dengan minItems dan maxItems dari min dan max. additionalProperties adalah false pada akar penyimpanan field dan di baris repeater. Field bernilai objek seperti tautan dan objek khusus dapat memiliki metadatanya sendiri. Blok tanpa field tidak memiliki properties, sehingga hanya objek kosong yang cocok.

Setiap field dijelaskan dalam bentuk kanonis yang diterima oleh bs_validate_block():

Field Schema
text, textarea, richtext, wysiwyg, code, date, datetime, unit, classes, html-tag, block String.
number, range Angka, dengan minimum dan maximum dari min dan max.
toggle Boolean.
select, radio, checkbox Nilai opsi, atau daftar nilai opsi untuk checkbox dan multiple, dengan enum.
color, gradient String, dengan enum jika disableCustomColors atau disableCustomGradients ditetapkan.
token Daftar string.
files ID lampiran bilangan bulat nonnegatif, atau daftar ID dengan multiple.
link Objek dengan url, title, dan opensInNewTab; url wajib diisi.
icon Objek dengan set, subSet, dan icon; set dan icon wajib diisi.
attributes Daftar objek dengan attribute yang tidak kosong dan value skalar.
repeater Daftar objek baris.
Jenis field khusus Jenis atribut yang terdaftar.

enum mencantumkan opsi yang diperiksa validasi: opsi statis dan opsi populate yang sudah diselesaikan saat pendaftaran. Opsi fetch jarak jauh dan argumen populate yang berisi {attributes.*} tidak memiliki enum. Kunci dengan definisi yang memiliki bentuk penyimpanan berbeda tidak disertakan, karena validasi melaporkan setiap nilai yang disimpan di bawahnya. Jika field blok dan field ekstensi menggunakan kunci yang sama, enum mencantumkan nilai yang diterima keduanya. Repeater bersama menggabungkan field turunannya dan menerapkan batas baris yang lebih ketat dari kedua definisi. Di dalam baris repeater, field pertama dengan ID yang cocok dari setiap sumber akan diterapkan, seperti saat render. Field eksplisit bernama <id>__size diutamakan daripada pendamping ukuran file yang ditambahkan secara otomatis.

Jika field tertutup tidak memiliki pilihan yang tersedia, atau dua set opsi yang berlaku tidak memiliki irisan, nilai kanonisnya adalah null untuk pilihan tunggal atau daftar kosong untuk pilihan jamak. Daftar opsi kosong tidak membuat field menjadi tanpa batasan. Pilihan jarak jauh dan pilihan yang bergantung pada atribut tetap terbuka.

label suatu field menjadi title, help-nya menjadi description, dan default-nya dipertahankan sebagai anotasi. title milik schema itu sendiri adalah judul blok. Field tidak pernah wajib diisi, dan logika kondisional bukan bagian dari schema.

Kendala hanya menggunakan kata kunci yang diperiksa oleh rest_validate_value_from_schema(), sehingga schema ini dapat langsung digunakan sebagai schema input untuk rute REST atau sebuah ability:

PHP
$values = $block['attrs']['blockstudio']['attributes'] ?? [];
$schema = bs_block_schema($block['blockName']);
if ($schema !== null) {
  $result = rest_validate_value_from_schema($values, $schema);
}

Skema menjelaskan satu formulir untuk setiap bidang; validasi juga menerima bentuk impor seperti objek opsi, string numerik, dan objek ID. Skema ini tidak menggantikan bs_validate_block(): konflik definisi adalah masalah konfigurasi dan tetap dapat menghasilkan temuan meskipun kunci yang berkonflik dihilangkan. Filter validasi juga dapat menerapkan aturan khusus situs. Gunakan bs_validate_block() untuk memeriksa konten tersimpan. Situs dengan resolver khusus saat render dapat menyesuaikan skema menggunakan filter blockstudio/blocks/attributes/schema.

Fungsi PHP

Tanpa Data

Dalam bentuk paling sederhana, fungsi ini menerima satu nilai berupa ID blok yang harus dirender di halaman.

PHP
bs_render_block('blockstudio/cta');

Dengan Data

Untuk merender blok dengan data khusus, gunakan array sebagai pengganti satu nilai untuk parameter pertama. Nilai dalam kunci data akan diteruskan ke variabel $attributes dan $a di dalam templat blok Anda.

PHP
bs_render_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
]);

Bersarang

Blok dapat disarangkan satu sama lain menggunakan fungsi bs_block bersama variabel $content yang canggih di dalam templat blok Anda.

PHP
<div>
  <h1><?php echo $a['title']; ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
  <?php echo $content; ?>
</div>
PHP
echo bs_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
  'content' => bs_block([
    'id' => 'blockstudio/button',
    'data' => [
      'text' => 'Button Text',
    ]
  ])
]);

Blok tombol akan dirender sebagai pengganti variabel $content di dalam templat blok.

Blok tersemat yang dirender dengan bs_render_block() atau bs_block() selalu menghasilkan HTML yang telah diselesaikan frontend, bahkan saat blok induk sedang merender pratinjau editor. Pseudo-komponen templat seperti <RichText /> dan <InnerBlocks /> diselesaikan sebelum blok tersemat dikembalikan.

Beberapa Slot

Anda juga dapat membuat beberapa slot konten dengan mengubah variabel $content menjadi array asosiatif dan memanggil kunci yang sesuai di fungsi bs_block.

PHP
<div>
  <?php echo $content['beforeContent']; ?>
  <h1><?php echo $a['title']; ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
  <?php echo $content['afterContent']; ?>
</div>
PHP
echo bs_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
  'content' => [
    'beforeContent' => bs_block([
      'id' => 'blockstudio/badge',
      'data' => ['text' => 'Before Content']
    ]),
    'afterContent' => bs_block([
      'id' => 'blockstudio/button',
      'data' => ['text' => 'Button Text']
    ])
  ]
]);

Tag Blok

Sematkan blok apa pun menggunakan sintaks tag HTML. Dua format didukung:

HTML
<bs:acme-hero title="Welcome" />
<block name="acme/hero" title="Welcome" />

Keduanya merender blok yang sama. Sintaks <bs:> mengubah tanda hubung menjadi pemisah namespace (acme-hero menjadi acme/hero). Tanda hubung dicoba dari kiri ke kanan dan kandidat terdaftar pertama yang cocok akan digunakan, sehingga namespace yang berisi tanda hubung juga dapat ditemukan: <bs:acme-ui-button> mencoba acme/ui-button, lalu acme-ui/button. Sintaks <block> menggunakan nama blok lengkap sebagai atribut name.

Blok Blockstudio maupun blok inti WordPress dapat digunakan. Blok Blockstudio dirender melalui seluruh alur (templat, Tailwind, aset). Blok inti dirender melalui sistem perenderan blok milik WordPress menggunakan perender blok bawaan.

Cara kerjanya

Tag blok berperilaku berbeda bergantung pada tempat kemunculannya:

Di dalam templat blok dan konten postingan, tag diganti dengan HTML yang telah dirender saat runtime. Hasilnya adalah markup akhir dari blok yang dirujuk, disematkan langsung ke halaman. Tidak ada blok WordPress di editor untuk tag ini. Tag ini hanya berfungsi sebagai mekanisme perenderan.

Di Halaman, Pola, dan Templat Situs, tag diubah menjadi blok WordPress native sebelum sumber file disinkronkan atau didaftarkan ke WordPress. Artinya, blok muncul di editor, dapat diedit jika target mendukung pengeditan, dan mengikuti seluruh siklus hidup blok milik WordPress. Sintaks tag ini merupakan singkatan untuk mendefinisikan konten blok di file templat.

Perbedaan ini penting: tag blok di templat menghasilkan output, sedangkan tag blok di halaman, pola, dan Templat Situs menghasilkan blok native.

Di dalam templat blok

Tag blok dirender secara otomatis di dalam templat Twig dan PHP. Tidak perlu pengaturan. Ini mencakup sintaks <bs:> dan <block> serta tag awalan dan alias terdaftar apa pun, sehingga templat dapat langsung mengeluarkannya alih-alih memanggil bs_render_block(). Output dirender HTML dan disematkan langsung ke output templat blok:

Twig
<div class="my-page">
  <bs:mytheme-card title="Featured" />
  <block name="core/separator" />
  <bs:core-paragraph>Rendered by WordPress</bs:core-paragraph>
  <block name="core/heading" level="2">Also WordPress</block>
  <theme-card title="Prefix shorthand" />
</div>

Di dalam konten postingan

Perenderan tingkat halaman (konten postingan, area widget) bersifat opsional:

JSON
{
  "blockTags": {
    "enabled": true
  }
}

Atau melalui filter:

PHP
add_filter('blockstudio/settings/block_tags/enabled', '__return_true');

Sintaks

Tag tanpa penutup:

HTML
<bs:mytheme-cta title="Get started" variant="primary" />
<block name="core/separator" />

Tag berpasangan dengan konten di dalamnya:

HTML
<bs:mytheme-section layout="wide">
  <p>Content inside the block.</p>
</bs:mytheme-section>

<block name="core/group">
  <block name="core/paragraph">Inside a group.</block>
</block>

Gabungkan sesuka hati. Kedua sintaks dapat disarangkan satu sama lain:

HTML
<bs:mytheme-section>
  <block name="core/heading" level="2">Title</block>
  <bs:mytheme-card title="Features" />
  <block name="core/paragraph">Description text.</block>
</bs:mytheme-section>

Singkatan awalan

Tag blok juga dapat menggunakan singkatan awalan khusus proyek. Daftarkan awalan dengan satu atau beberapa namespace, lalu Blockstudio akan menyelesaikan <prefix-slug> ke blok terdaftar pertama sesuai urutan namespace:

PHP
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
  $prefixes['theme'] = ['theme-components', 'bsui'];

  return $prefixes;
});
HTML
<theme-card title="Homepage" />
<theme-button label="Get started" />
<theme-ui-feature-matrix />

Dengan contoh di atas, <theme-card> diselesaikan menjadi theme-components/card, <theme-button> menggunakan bsui/button sebagai alternatif jika theme-components/button belum terdaftar, dan <theme-ui-feature-matrix> diselesaikan menjadi theme-components/ui-feature-matrix.

Awalan juga dapat disusun berlapis. Jika tag berawalan tidak dapat diselesaikan secara langsung dan slug yang tersisa merupakan tag awalan terdaftar, proses penyelesaian akan berulang sehingga awalan merek dapat berada di atas awalan namespace:

PHP
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
  $prefixes['theme'] = ['theme-components'];
  $prefixes['ui'] = ['bsui'];

  return $prefixes;
});
HTML
<theme-ui-input />

<theme-ui-input> tidak memiliki blok theme-components/ui-input, sehingga proses berlanjut ke awalan ui dan menyelesaikan bsui/input. Kecocokan langsung selalu diprioritaskan daripada penyelesaian bersarang, dan aturan izinkan/tolak berlaku pada blok akhir yang diselesaikan.

Anda juga dapat mengonfigurasi awalan di blockstudio.json:

JSON
{
  "blockTags": {
    "prefixes": {
      "theme": ["theme-components", "bsui"]
    }
  }
}

Awalan harus berupa huruf kecil atau angka, diawali huruf, dan tidak boleh berisi tanda hubung. Alias eksplisit dari blockstudio/block_tags/tag_aliases lebih diprioritaskan daripada penyelesaian awalan. Tag berawalan yang tidak dikenal dibiarkan apa adanya.

Tag awalan dan alias tetap didukung sebagai kemudahan penulisan. Ejaan kanonis yang portabel selalu <bs:namespace-slug>, karena mencatat nama blok sebenarnya tanpa bergantung pada filter proyek:

HTML
<bs:theme-components-card />
<bs:bsui-input />

Contoh Blockstudio, diagnostik yang dihasilkan, dan output programatik menggunakan ejaan kanonis ini. Proyek yang ingin menghapus bentuk singkatan lama dapat menggunakan migrasi tag kanonis mandiri yang mengutamakan uji coba tanpa menjalankan WordPress.

Blok inti

Blok apa pun dengan perender terdaftar dapat digunakan:

HTML
<bs:core-paragraph>A paragraph</bs:core-paragraph>
<bs:core-heading level="2">A heading</bs:core-heading>
<bs:core-separator />
<bs:core-image url="photo.jpg" alt="Photo" />
<bs:core-buttons>
  <bs:core-button url="/about">About</bs:core-button>
</bs:core-buttons>

Atau dengan sintaks <block>:

HTML
<block name="core/group">
  <block name="core/columns">
    <block name="core/column">
      <block name="core/paragraph">Left column</block>
    </block>
    <block name="core/column">
      <block name="core/paragraph">Right column</block>
    </block>
  </block>
</block>

Daftar izinkan dan tolak

Atur blok mana yang dapat dirender melalui tag:

JSON
{
  "blockTags": {
    "enabled": true,
    "allow": ["mytheme/*", "core/*"],
    "deny": ["mytheme/internal-*"]
  }
}

allow membatasi hanya pada pola yang cocok. deny mengecualikan pola yang cocok dan lebih diprioritaskan. Keduanya mendukung wildcard * melalui fnmatch(). Aturan ini berlaku untuk kedua sintaks serta perenderan tingkat templat dan halaman.

Filter: blockstudio/block_tags/allow dan blockstudio/block_tags/deny.

Penerusan HTML

Atribut yang diawali data- diteruskan ke elemen root blok yang dirender. Atribut yang diawali html- juga diteruskan, dengan awalan dihapus. Berfungsi dengan kedua sintaks. Atribut yang diteruskan menggantikan nilai yang sudah ada pada elemen root, bukan menggabungkannya, sehingga html-class menggantikan kelas milik blok.

Blok Blockstudio juga menempatkan atribut global yang tidak dideklarasikan sebagai field pada elemen root-nya: id, style, role, title, lang, dir, hidden, tabindex, dan setiap atribut aria-*. Field yang dideklarasikan selalu diprioritaskan, jadi blok dengan field title akan menerima nilai di $a['title']. Gaya yang diteruskan melewati safecss_filter_attr(), filter WordPress berlaku untuk atribut gaya dalam konten postingan, dan gaya tersebut ditambahkan ke gaya yang sudah ditetapkan templat.

Nilai atribut berupa HTML, sehingga entitas didekode satu kali saat tag diurai: title="Tom &amp; Jerry" diterima templat sebagai Tom & Jerry dan di-escape kembali saat dikeluarkan. Nilai dalam tanda kutip dapat berisi >, seperti varian Tailwind dan pemilih animasi, baik pada tag tanpa penutup maupun tag berpasangan.

Atribut lain apa pun yang tidak dideklarasikan oleh blok, termasuk class, tidak pernah diteruskan ke HTML. Jika WP_DEBUG diaktifkan, Blockstudio melaporkan setiap atribut tersebut satu kali per permintaan melalui _doing_it_wrong(). Deklarasikan field untuk atribut itu, atau tulis sebagai atribut data-, aria-, atau html-.

HTML
<bs:mytheme-card
  title="My Card"
  html-class="featured-card"
  html-id="main-card"
  data-analytics="card-click"
/>

<block name="core/paragraph" html-class="highlight" data-section="intro">
  Highlighted paragraph.
</block>

Perender khusus

Daftarkan perender blok khusus untuk jenis blok tambahan. Perender menerima array atribut dan string konten dalam, lalu mengembalikan array blok WordPress:

PHP
add_filter('blockstudio/block_tags/builders', function ($builders, $parser) {
    $builders['myplugin/custom-block'] = function (array $attrs, string $inner_content) {
        $html = '<div class="my-block">' . $inner_content . '</div>';
        return [
            'blockName'    => 'myplugin/custom-block',
            'attrs'        => $attrs,
            'innerBlocks'  => [],
            'innerHTML'    => $html,
            'innerContent' => [$html],
        ];
    };
    return $builders;
}, 10, 2);

Untuk blok kontainer yang perlu mengurai konten dalam menjadi blok anak, tambahkan entri kedua di filter yang sama:

PHP
$builders['myplugin/wrapper'] = function (array $attrs, string $inner_content) {
    $inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks($inner_content);
    $content = ['<div class="my-wrapper">'];
    foreach ($inner_blocks as $block) {
        $content[] = null;
    }
    $content[] = '</div>';
    return [
        'blockName'    => 'myplugin/wrapper',
        'attrs'        => $attrs,
        'innerBlocks'  => $inner_blocks,
        'innerHTML'    => '<div class="my-wrapper"></div>',
        'innerContent' => $content,
    ];
};

blockstudio/block_tags/builders berlaku untuk tag blok dan blok khusus yang dipilih melalui blockstudio/parser/element_mapping. Ini adalah hook yang tepat ketika blok proyek dengan pemetaan elemen perlu memindahkan teks dalam ke field Blockstudio atau menyusun array blok khusus.

blockstudio/block_tags/renderers dan blockstudio/parser/renderers menerima registry dan bentuk callback yang sama. Keduanya tetap tersedia untuk kompatibilitas dan penggantian akhir pada tingkat parser. Filter dijalankan dengan urutan berikut:

  1. blockstudio/block_tags/builders
  2. blockstudio/block_tags/renderers
  3. blockstudio/parser/renderers

Filter yang dijalankan belakangan dapat mengganti perender yang didaftarkan sebelumnya.

Penggunaan programatik

Terapkan perenderan tag ke string apa pun dari PHP:

PHP
$html = apply_filters('blockstudio/block_tags/render', $content);

Komponen

Tag blok cocok digunakan bersama Komponen. Komponen adalah blok yang hanya dirender secara programatik dan tidak pernah muncul di editor.

HTML
<bs:mytheme-card title="My Card" description="Card content." />

Parser

Tag blok diproses oleh pemindai string ringan yang menggantikan DOMDocument. Parser menangani sintaks <bs:> dan <block>, tag bernama sama yang bersarang dengan pelacakan kedalaman, nilai atribut dalam tanda kutip, serta blok kontainer rekursif. Parser ini dirancang khusus untuk kasus penggunaan tersebut, lebih cepat dalam tolok ukur daripada DOMDocument dan WordPress milik WP_HTML_Tag_Processor, serta menghindari masalah DOMDocument yang diketahui terkait penghapusan awalan namespace dan pengubahan atribut menjadi huruf kecil.

Untuk Halaman, Pola, dan Templat Situs, parser yang sama juga menangani elemen HTML mentah (<p>, <div>, <h1>, dan lainnya), lalu memetakannya ke blok inti WordPress yang sesuai.

Saat pemetaan elemen mengarahkan <p> ke blok Blockstudio non-inti yang terdaftar dan mendeklarasikan atribut richtext content, konten HTML di dalamnya otomatis diteruskan ke atribut content tersebut, termasuk tag inline seperti code dan img yang dipetakan pada tingkat blok. Paragraf yang satu-satunya anak adalah gambar akan menjadi blok yang dipetakan oleh <img>. Tag blok bersarang atau HTML tingkat blok tetap menggunakan penguraian blok dalam seperti biasa. <block name="core/shortcode"> mempertahankan teks shortcode-nya sebagai konten blok.